@monoes/monograph 1.6.0 → 1.6.2

package/dist/src/cache/extraction-cache.d.ts

@@ -1,4 +1,4 @@
-import type { MonographEdge, MonographNode } from '../types.js';
+import { type MonographEdge, type MonographNode } from '../types.js';
 /**
  * Bump this whenever the parser/extractor output format changes in a way that
  * would make previously-cached nodes/edges stale or wrong (e.g. a parser bugfix,
@@ -15,6 +15,8 @@ export interface CacheEntry {
     edges: MonographEdge[];
     /** Extraction format version this entry was written under — see EXTRACTION_CACHE_VERSION. */
     cacheVersion?: number;
+    /** Symbol-identity scheme this entry's node IDs were minted under — see SYMBOL_ID_VERSION. */
+    symbolIdVersion?: number;
 }
 export declare class ExtractionCache {
     private readonly dir;

package/dist/src/cache/extraction-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extraction-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/extraction-cache.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,OAAO,CAA6C;IAE5D,YAA6B,GAAG,EAAE,MAAM,EAEvC;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjC;IAED,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnC;IAED,OAAO,CAAC,SAAS;IAKjB;8DAC0D;IAC1D,OAAO,CAAC,WAAW;IAcnB;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,SAA2B,GAAG,MAAM,CAqBjD;IAED;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAuB/C;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAUzD;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI,CAmB5F;IAED,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,aAAa,EAAE,GACrB,IAAI,CAmBN;IAED,KAAK,IAAI,IAAI,CASZ;CACF"}
+{"version":3,"file":"extraction-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/extraction-cache.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAqB,MAAM,aAAa,CAAC;AAExF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAU1C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAUD,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,OAAO,CAA6C;IAE5D,YAA6B,GAAG,EAAE,MAAM,EAEvC;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjC;IAED,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnC;IAED,OAAO,CAAC,SAAS;IAKjB;8DAC0D;IAC1D,OAAO,CAAC,WAAW;IAcnB;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,SAA2B,GAAG,MAAM,CAqBjD;IAED;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAuB/C;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAUzD;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI,CAoB5F;IAED,WAAW,CACT,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,aAAa,EAAE,GACrB,IAAI,CAoBN;IAED,KAAK,IAAI,IAAI,CASZ;CACF"}

package/dist/src/cache/extraction-cache.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
+import { SYMBOL_ID_VERSION } from '../types.js';
 /**
  * Bump this whenever the parser/extractor output format changes in a way that
  * would make previously-cached nodes/edges stale or wrong (e.g. a parser bugfix,
@@ -9,6 +10,11 @@ import { join } from 'node:path';
  * bumping this effectively invalidates the entire on-disk extraction cache.
  */
 export const EXTRACTION_CACHE_VERSION = 1;
+/** An entry is reusable only if BOTH the extraction format and the symbol-identity scheme match. */
+function isCurrentVersion(entry) {
+    return (entry.cacheVersion === EXTRACTION_CACHE_VERSION &&
+        (entry.symbolIdVersion ?? 0) === SYMBOL_ID_VERSION);
+}
 export class ExtractionCache {
     dir;
     pending = [];
@@ -85,7 +91,7 @@ export class ExtractionCache {
             return null;
         try {
             const entry = JSON.parse(readFileSync(p, 'utf-8'));
-            if (entry.cacheVersion !== EXTRACTION_CACHE_VERSION)
+            if (!isCurrentVersion(entry))
                 return null;
             const st = statSync(filePath);
             if (entry.mtimeMs === st.mtimeMs && entry.size === st.size)
@@ -115,7 +121,7 @@ export class ExtractionCache {
             return null;
         try {
             const entry = JSON.parse(readFileSync(p, 'utf-8'));
-            if (entry.cacheVersion !== EXTRACTION_CACHE_VERSION)
+            if (!isCurrentVersion(entry))
                 return null;
             return entry.fileHash === fileHash ? entry : null;
         }
@@ -141,6 +147,7 @@ export class ExtractionCache {
             nodes,
             edges,
             cacheVersion: EXTRACTION_CACHE_VERSION,
+            symbolIdVersion: SYMBOL_ID_VERSION,
         };
         this.writeAtomic(this.entryPath(filePath), JSON.stringify(entry));
     }
@@ -162,6 +169,7 @@ export class ExtractionCache {
             nodes,
             edges,
             cacheVersion: EXTRACTION_CACHE_VERSION,
+            symbolIdVersion: SYMBOL_ID_VERSION,
         };
         this.pending.push({ path: this.entryPath(filePath), data: JSON.stringify(entry) });
     }

package/dist/src/cache/extraction-cache.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/graph/explain.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,EA4DhC,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE/D;AAED,wBAAgB,SAAS,IAAI,OAAO,EAAE,CAErC;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,EAAE,CAKjE;AAID,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,EAAE,OAAO,EA+BjC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,OAAO,EAOhC,CAAC;AAEF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CA0B7D;AAED,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKpD;AAED,wBAAgB,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKnD"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/graph/explain.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,WAAW,EAAE,OAAO,EAqEhC,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE/D;AAED,wBAAgB,SAAS,IAAI,OAAO,EAAE,CAErC;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,EAAE,CAKjE;AAID,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,EAAE,OAAO,EA+BjC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,OAAO,EAOhC,CAAC;AAEF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CA0B7D;AAED,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKpD;AAED,wBAAgB,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKnD"}

package/dist/src/graph/explain.js

@@ -51,8 +51,15 @@ export const CHECK_RULES = [
         id: 'low-cohesion',
         name: 'Low Community Cohesion',
         description: 'A module community with a low ratio of internal to possible edges.',
-        rationale: 'Low cohesion means the community is an arbitrary grouping, not a real module.',
-        remediation: 'Re-organize files so that related functionality is co-located.',
+        rationale: 'The members of this community are sparsely connected to each other in the clustered ' +
+            'graph. That graph is a deliberate projection — coupling edges (calls, imports, ' +
+            'inheritance) count fully, containment is down-weighted, and prose relations are ' +
+            'excluded — so the number measures structural connectivity under those weights, not ' +
+            'module quality. Weak connectivity is consistent with an arbitrary grouping, but also ' +
+            'with a genuine module whose cohesion is by convention, configuration, or a shared ' +
+            'concern the parser does not see.',
+        remediation: 'Read the members and decide whether they belong together. If they do not, co-locate ' +
+            'related functionality; if they do, no change is needed.',
         severity: 'info',
     },
 ];

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

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

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

@@ -8,7 +8,11 @@ export interface PageRankOptions {
     tolerance?: number;
 }
 /**
- * Evict cached statements and results for a given DB instance (call after writes).
+ * Evict cached statements and results for a given DB connection (call after writes).
+ *
+ * Closing a connection needs no explicit call: both caches are keyed by the
+ * connection object, so a reopened database gets freshly prepared statements
+ * and an empty result cache.
  */
 export declare function invalidatePageRankCache(db: MonographDb): void;
 /**
@@ -18,8 +22,10 @@ export declare function invalidatePageRankCache(db: MonographDb): void;
  * After convergence the scores still sum to ~1 (standard normalized PageRank).
  * Dangling nodes (out-degree 0) distribute their rank equally to all nodes.
  *
- * Results are cached for 5 seconds when the graph's node+edge counts are
- * unchanged, making repeated calls (e.g. during context preloading) free.
+ * Results are cached for 5 seconds per connection when both the graph's
+ * content revision and the algorithm options are unchanged, making repeated
+ * calls (e.g. during context preloading) free. Each call returns its own Map,
+ * so a caller mutating the result cannot corrupt another caller's copy.
  *
  * @param db - The MonographDb instance
  * @param options - Optional tuning parameters

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

@@ -1 +1 @@
-{"version":3,"file":"pagerank.d.ts","sourceRoot":"","sources":["../../../src/graph/pagerank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiDD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAO7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,GAAE,eAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA+E5F"}
+{"version":3,"file":"pagerank.d.ts","sourceRoot":"","sources":["../../../src/graph/pagerank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiFD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAG7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,GAAE,eAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuF5F"}

package/dist/src/graph/pagerank.js

@@ -1,43 +1,68 @@
-const _stmtCache = new Map();
+const _stmtCache = new WeakMap();
 function getStmts(db) {
-    const key = db.name ?? '__default__';
-    let cache = _stmtCache.get(key);
+    let cache = _stmtCache.get(db);
     if (!cache) {
-        if (_stmtCache.size >= MAX_STMT_CACHE) {
-            const oldest = _stmtCache.keys().next().value;
-            _stmtCache.delete(oldest);
-        }
         cache = {
             selectNodes: db.prepare('SELECT id FROM nodes'),
             selectEdges: db.prepare('SELECT source_id, target_id FROM edges'),
         };
-        _stmtCache.set(key, cache);
+        _stmtCache.set(db, cache);
     }
     return cache;
 }
 // ---------------------------------------------------------------------------
-// Result cache — avoids re-running power iteration when the graph hasn't
-// changed. Keyed by (dbName, nodeCount, edgeCount) with a 5-second TTL.
+// Result cache — avoids re-running power iteration when the graph and the
+// algorithm options are both unchanged. Also keyed per connection, with an
+// inner key of (graph revision, options) and a 5-second TTL.
 // ---------------------------------------------------------------------------
 const PAGERANK_CACHE_TTL_MS = 5_000;
 const MAX_RESULT_CACHE = 50;
-const MAX_STMT_CACHE = 20;
-const _resultCache = new Map();
-function resultCacheKey(db, nodeCount, edgeCount) {
-    const name = db.name ?? '__default__';
-    return `${name}:${nodeCount}:${edgeCount}`;
+const _resultCache = new WeakMap();
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/**
+ * Cheap content revision for the graph that was just read.
+ *
+ * There is no persisted graph-generation counter in the schema, and node/edge
+ * counts alone are not a topology marker: a graph can be rewired (edges moved
+ * between nodes) without either count changing. Both row sets have already
+ * been fetched by the time this runs, so hashing them costs O(N+E) — the same
+ * order as the fetch itself, and far less than the power iteration it guards.
+ *
+ * Row order is not guaranteed by SQLite; a reordering only produces a cache
+ * miss (a recompute), never a stale hit.
+ */
+function graphRevision(nodeRows, edgeRows) {
+    let h1 = FNV_OFFSET;
+    let h2 = 0xcbf29ce4;
+    const byte = (c) => {
+        h1 = Math.imul(h1 ^ c, FNV_PRIME);
+        h2 = Math.imul(h2 + c, 0x85ebca6b) ^ (h2 >>> 13);
+    };
+    const field = (s) => {
+        for (let i = 0; i < s.length; i++)
+            byte(s.charCodeAt(i));
+        byte(0x1f); // field separator — keeps ("ab","c") distinct from ("a","bc")
+    };
+    for (const r of nodeRows)
+        field(r.id);
+    for (const e of edgeRows) {
+        field(e.source_id);
+        field(e.target_id);
+    }
+    const hex = ((h1 >>> 0).toString(36) + (h2 >>> 0).toString(36)).padStart(2, '0');
+    return `${hex}:${nodeRows.length}:${edgeRows.length}`;
 }
 /**
- * Evict cached statements and results for a given DB instance (call after writes).
+ * Evict cached statements and results for a given DB connection (call after writes).
+ *
+ * Closing a connection needs no explicit call: both caches are keyed by the
+ * connection object, so a reopened database gets freshly prepared statements
+ * and an empty result cache.
  */
 export function invalidatePageRankCache(db) {
-    const key = db.name ?? '__default__';
-    _stmtCache.delete(key);
-    // Purge all result-cache entries for this DB (they have the name as prefix)
-    for (const k of _resultCache.keys()) {
-        if (k.startsWith(`${key}:`))
-            _resultCache.delete(k);
-    }
+    _stmtCache.delete(db);
+    _resultCache.delete(db);
 }
 /**
  * Compute PageRank scores for all nodes using power iteration.
@@ -46,8 +71,10 @@ export function invalidatePageRankCache(db) {
  * After convergence the scores still sum to ~1 (standard normalized PageRank).
  * Dangling nodes (out-degree 0) distribute their rank equally to all nodes.
  *
- * Results are cached for 5 seconds when the graph's node+edge counts are
- * unchanged, making repeated calls (e.g. during context preloading) free.
+ * Results are cached for 5 seconds per connection when both the graph's
+ * content revision and the algorithm options are unchanged, making repeated
+ * calls (e.g. during context preloading) free. Each call returns its own Map,
+ * so a caller mutating the result cannot corrupt another caller's copy.
  *
  * @param db - The MonographDb instance
  * @param options - Optional tuning parameters
@@ -60,12 +87,15 @@ export function pageRank(db, options = {}) {
     const edgeRows = stmts.selectEdges.all();
     if (nodeRows.length === 0)
         return new Map();
-    // Check result cache before running power iteration
-    const cacheKey = resultCacheKey(db, nodeRows.length, edgeRows.length);
+    // Check result cache before running power iteration. The key covers both the
+    // graph's content revision and every option that changes the output, so a
+    // rewired graph or a different damping factor can never hit a stale entry.
+    const cacheKey = `${graphRevision(nodeRows, edgeRows)}|${dampingFactor}|${maxIterations}|${tolerance}`;
     const now = Date.now();
-    const cached = _resultCache.get(cacheKey);
+    let dbCache = _resultCache.get(db);
+    const cached = dbCache?.get(cacheKey);
     if (cached && now < cached.expiresAt)
-        return cached.result;
+        return new Map(cached.result);
     const nodes = nodeRows.map((r) => r.id);
     const n = nodes.length;
     const nodeIndex = new Map();
@@ -115,11 +145,16 @@ export function pageRank(db, options = {}) {
     for (let i = 0; i < n; i++) {
         result.set(nodes[i], scores[i]);
     }
-    if (_resultCache.size >= MAX_RESULT_CACHE) {
-        const oldest = _resultCache.keys().next().value;
-        _resultCache.delete(oldest);
+    if (!dbCache) {
+        dbCache = new Map();
+        _resultCache.set(db, dbCache);
+    }
+    if (dbCache.size >= MAX_RESULT_CACHE) {
+        const oldest = dbCache.keys().next().value;
+        dbCache.delete(oldest);
     }
-    _resultCache.set(cacheKey, { result, expiresAt: now + PAGERANK_CACHE_TTL_MS });
-    return result;
+    dbCache.set(cacheKey, { result, expiresAt: now + PAGERANK_CACHE_TTL_MS });
+    // Hand out a copy so a caller mutating its result can't corrupt the cache.
+    return new Map(result);
 }
 //# sourceMappingURL=pagerank.js.map

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

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

package/dist/src/mcp-tools/neighbors.d.ts

@@ -7,13 +7,39 @@ export interface NeighborEntry {
     confidenceScore: number;
     direction: 'outbound' | 'inbound';
 }
+/** A node a name could have referred to — enough to re-query unambiguously. */
+export interface NeighborCandidate {
+    id: string;
+    name: string;
+    label: string;
+    filePath: string | null;
+    startLine: number | null;
+}
 export interface MonographNeighborsResult {
     node: MonographNode | null;
     neighbors: NeighborEntry[];
+    /** True when `name` matched several nodes and nothing narrowed it to one. */
+    ambiguous: boolean;
+    /** Populated when ambiguous — re-query with `nodeId` or `filePath`. */
+    candidates: NeighborCandidate[];
+    /** Neighbors matching the query before `limit` was applied. */
+    totalNeighbors: number;
+    /** True when `totalNeighbors` exceeds the returned `neighbors`. */
+    truncated: boolean;
+    /** The cap that was applied per direction. */
+    limit: number;
 }
-export declare function getMonographNeighbors(db: Database.Database, input: {
-    name: string;
+export interface MonographNeighborsInput {
+    /** Canonical node id — the unambiguous way to address a node. */
+    nodeId?: string;
+    /** Symbol name; may match several nodes. */
+    name?: string;
+    /** Narrows an ambiguous `name` — exact file path or a trailing fragment of one. */
+    filePath?: string;
     relationFilter?: string;
     includeInbound?: boolean;
-}): MonographNeighborsResult;
+    /** Max neighbors per direction (default 50, hard cap 500). */
+    limit?: number;
+}
+export declare function getMonographNeighbors(db: Database.Database, input: MonographNeighborsInput): MonographNeighborsResult;
 //# sourceMappingURL=neighbors.d.ts.map

package/dist/src/mcp-tools/neighbors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"neighbors.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/neighbors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,UAAU,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AA+BD,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GACzE,wBAAwB,CAc1B"}
+{"version":3,"file":"neighbors.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/neighbors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,UAAU,GAAG,SAAS,CAAC;CACnC;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuFD,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,uBAAuB,GAC7B,wBAAwB,CAiD1B"}

package/dist/src/mcp-tools/neighbors.js

@@ -1,13 +1,28 @@
 import { rowToNode } from '../storage/node-store.js';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+/** Candidate lists exist to be read by a human or an agent; a long one is noise. */
+const CANDIDATE_CAP = 25;
 // ── Shared edge query helper ──────────────────────────────────────────────────
-function queryEdges(db, nodeId, direction, relationFilter) {
+function edgeColumns(direction) {
     // outbound: source_id = nodeId → join target_id
     // inbound:  target_id = nodeId → join source_id
-    const [idCol, joinCol] = direction === 'outbound' ? ['source_id', 'target_id'] : ['target_id', 'source_id'];
+    return direction === 'outbound' ? ['source_id', 'target_id'] : ['target_id', 'source_id'];
+}
+function countEdges(db, nodeId, direction, relationFilter) {
+    const [idCol] = edgeColumns(direction);
     const sql = relationFilter
-        ? `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? AND e.relation = ? LIMIT 50`
-        : `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? LIMIT 50`;
+        ? `SELECT COUNT(*) AS c FROM edges e WHERE e.${idCol} = ? AND e.relation = ?`
+        : `SELECT COUNT(*) AS c FROM edges e WHERE e.${idCol} = ?`;
     const params = relationFilter ? [nodeId, relationFilter] : [nodeId];
+    return db.prepare(sql).get(...params).c;
+}
+function queryEdges(db, nodeId, direction, relationFilter, limit) {
+    const [idCol, joinCol] = edgeColumns(direction);
+    const sql = relationFilter
+        ? `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? AND e.relation = ? LIMIT ?`
+        : `SELECT n.*, e.relation, e.confidence, e.confidence_score FROM nodes n JOIN edges e ON n.id = e.${joinCol} WHERE e.${idCol} = ? LIMIT ?`;
+    const params = relationFilter ? [nodeId, relationFilter, limit] : [nodeId, limit];
     const rows = db.prepare(sql).all(...params);
     return rows.map((row) => ({
         node: rowToNode(row),
@@ -17,15 +32,75 @@ function queryEdges(db, nodeId, direction, relationFilter) {
         direction,
     }));
 }
+// ── Node resolution ───────────────────────────────────────────────────────────
+function toCandidate(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        label: row.label,
+        filePath: row.file_path ?? null,
+        startLine: row.start_line ?? null,
+    };
+}
+/** Exact path match, else a trailing-fragment match so `user.ts` narrows `/app/user.ts`. */
+function matchesFilePath(row, filePath) {
+    const rowPath = row.file_path ?? '';
+    return rowPath === filePath || rowPath.endsWith(filePath);
+}
+function emptyResult(limit, candidates = []) {
+    return {
+        node: null,
+        neighbors: [],
+        ambiguous: candidates.length > 1,
+        candidates,
+        totalNeighbors: 0,
+        truncated: false,
+        limit,
+    };
+}
 export function getMonographNeighbors(db, input) {
-    const nodeRow = db.prepare('SELECT * FROM nodes WHERE name = ? LIMIT 1').get(input.name);
-    if (!nodeRow)
-        return { node: null, neighbors: [] };
+    const limit = Math.min(Math.max(input.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+    let nodeRow;
+    if (input.nodeId) {
+        nodeRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(input.nodeId);
+        if (!nodeRow)
+            return emptyResult(limit);
+    }
+    else if (input.name) {
+        const rows = db
+            .prepare('SELECT * FROM nodes WHERE name = ? LIMIT ?')
+            .all(input.name, CANDIDATE_CAP + 1);
+        const matches = input.filePath
+            ? rows.filter((r) => matchesFilePath(r, input.filePath))
+            : rows;
+        if (matches.length === 0)
+            return emptyResult(limit);
+        if (matches.length > 1) {
+            // A confident answer about the wrong node is worse than asking which one.
+            return emptyResult(limit, matches.slice(0, CANDIDATE_CAP).map(toCandidate));
+        }
+        nodeRow = matches[0];
+    }
+    else {
+        return emptyResult(limit);
+    }
     const node = rowToNode(nodeRow);
     const neighbors = [
-        ...queryEdges(db, node.id, 'outbound', input.relationFilter),
-        ...(input.includeInbound ? queryEdges(db, node.id, 'inbound', input.relationFilter) : []),
+        ...queryEdges(db, node.id, 'outbound', input.relationFilter, limit),
+        ...(input.includeInbound
+            ? queryEdges(db, node.id, 'inbound', input.relationFilter, limit)
+            : []),
     ];
-    return { node, neighbors };
+    const totalNeighbors = countEdges(db, node.id, 'outbound', input.relationFilter) +
+        (input.includeInbound ? countEdges(db, node.id, 'inbound', input.relationFilter) : 0);
+    return {
+        node,
+        neighbors,
+        ambiguous: false,
+        candidates: [],
+        totalNeighbors,
+        truncated: totalNeighbors > neighbors.length,
+        limit,
+    };
 }
 //# sourceMappingURL=neighbors.js.map

package/dist/src/mcp-tools/neighbors.js.map

@@ -1 +1 @@
-{"version":3,"file":"neighbors.js","sourceRoot":"","sources":["../../../src/mcp-tools/neighbors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAgBrD,iFAAiF;AAEjF,SAAS,UAAU,CACjB,EAAqB,EACrB,MAAc,EACd,SAAiC,EACjC,cAAuB;IAEvB,gDAAgD;IAChD,gDAAgD;IAChD,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,GACpB,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAErF,MAAM,GAAG,GAAG,cAAc;QACxB,CAAC,CAAC,kGAAkG,OAAO,YAAY,KAAK,kCAAkC;QAC9J,CAAC,CAAC,kGAAkG,OAAO,YAAY,KAAK,eAAe,CAAC;IAE9I,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAA8B,CAAC;IAEzE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC;QACpB,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,UAAU,EAAE,GAAG,CAAC,UAAoB;QACpC,eAAe,EAAG,GAAG,CAAC,gBAA2B,IAAI,CAAC;QACtD,SAAS;KACV,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,EAAqB,EACrB,KAA0E;IAE1E,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAE1E,CAAC;IAEd,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAEnD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,SAAS,GAAoB;QACjC,GAAG,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC;QAC5D,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1F,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"neighbors.js","sourceRoot":"","sources":["../../../src/mcp-tools/neighbors.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp-tools/query.d.ts

@@ -1,3 +1,4 @@
+import type { RetrievalMode } from '../search/hybrid-query.js';
 import type { MonographDb } from '../storage/db.js';
 export interface QueryResult {
     id: string;
@@ -6,6 +7,7 @@ export interface QueryResult {
     filePath?: string;
     /** Line number where the symbol is defined — enables direct file:line navigation. */
     startLine?: number | null;
+    /** Higher is better, always ≥ 0 (monograph's single score convention). */
     score: number;
     isProcess: boolean;
 }
@@ -37,6 +39,11 @@ export declare const monographQueryTool: {
                 type: string;
                 description: string;
             };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
         };
         required: string[];
     };
@@ -45,6 +52,7 @@ export declare const monographQueryTool: {
         repoPath?: string;
         topK?: number;
         includeProcesses?: boolean;
+        mode?: RetrievalMode;
         db?: MonographDb;
     }): Promise<MonographQueryOutput>;
 };

package/dist/src/mcp-tools/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB;IAC7B,IAAI;IACJ,WAAW;IAGX,WAAW;QACT,IAAI,EAAE,QAAQ;QACd,UAAU;YACR,KAAK;gBAAI,IAAI;gBAAY,WAAW;;YACpC,QAAQ;gBAAI,IAAI;gBAAY,WAAW;;YACvC,IAAI;gBAAI,IAAI;gBAAY,WAAW;;YACnC,gBAAgB;gBACd,IAAI;gBACJ,WAAW;;;QAGf,QAAQ;;IAEJ,OAAO,OAAO;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,EAAE,CAAC,EAAE,WAAW,CAAC;KAClB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2ClC,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB;IAC7B,IAAI;IACJ,WAAW;IAIX,WAAW;QACT,IAAI,EAAE,QAAQ;QACd,UAAU;YACR,KAAK;gBAAI,IAAI;gBAAY,WAAW;;YACpC,QAAQ;gBAAI,IAAI;gBAAY,WAAW;;YACvC,IAAI;gBAAI,IAAI;gBAAY,WAAW;;YACnC,gBAAgB;gBACd,IAAI;gBACJ,WAAW;;YAEb,IAAI;gBACF,IAAI;gBACJ,IAAI;gBACJ,WAAW;;;QAGf,QAAQ;;IAEJ,OAAO,OAAO;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,IAAI,CAAC,EAAE,aAAa,CAAC;QACrB,EAAE,CAAC,EAAE,WAAW,CAAC;KAClB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2ClC,CAAC"}