@memlab/mcp-server 2.3.0 → 2.52.0

package/dist/heap-state.js

@@ -42,6 +42,72 @@ function instrumentSnapshot(snapshot) {
 // don't take an explicit snapshot argument.
 const loaded = new Map();
 let currentHandle = null;
+// Monotonic access stamp per handle, for LRU eviction under memory pressure.
+// A counter rather than a clock: two snapshots can be touched inside the same
+// millisecond, and only the ORDER matters here.
+const lastUsed = new Map();
+let useCounter = 0;
+function touch(handle) {
+    if (handle != null)
+        lastUsed.set(handle, ++useCounter);
+}
+/**
+ * Drop the least-recently-used resident snapshot, never the current one.
+ * Returns its metadata, or null when there is nothing else to evict.
+ *
+ * Used by the loader's memory-headroom guard: with `keep_previous`, several
+ * full graphs stay resident, and the load that tips the process over is the one
+ * that dies — taking every resident snapshot with it. Evicting the coldest one
+ * first turns an OOM crash into a slower session.
+ */
+export function evictLeastRecentlyUsed() {
+    let victim = null;
+    let victimStamp = Infinity;
+    for (const handle of loaded.keys()) {
+        if (handle === currentHandle)
+            continue;
+        const stamp = lastUsed.get(handle) ?? 0;
+        if (stamp < victimStamp) {
+            victimStamp = stamp;
+            victim = handle;
+        }
+    }
+    if (victim == null)
+        return null;
+    const meta = loaded.get(victim)?.metadata ?? null;
+    loaded.delete(victim);
+    lastUsed.delete(victim);
+    dropEvalScratch(victim);
+    return meta;
+}
+// Per-snapshot scratch space for memlab_eval sessions: lets a custom script
+// build an index once (e.g. class/typename → ids) and reuse it across
+// subsequent eval calls instead of re-scanning millions of nodes every time.
+// Keyed by handle so switching snapshots never crosses the streams; dropped
+// when the snapshot is replaced/unloaded so a stale index can't outlive its
+// snapshot.
+const evalScratch = new Map();
+/**
+ * Returns the mutable scratch object for the current snapshot, creating it on
+ * first use. Node ids and any derived index are only valid for the snapshot they
+ * were built from, so the scratch is keyed to the active handle.
+ */
+export function getEvalScratch() {
+    const key = currentHandle ?? '__none__';
+    let s = evalScratch.get(key);
+    if (!s) {
+        s = {};
+        evalScratch.set(key, s);
+    }
+    return s;
+}
+function dropEvalScratch(handle) {
+    if (handle == null) {
+        evalScratch.clear();
+        return;
+    }
+    evalScratch.delete(handle);
+}
 const sessionConfig = {
     quietHeader: false,
     suppressSuggestions: false,
@@ -73,6 +139,46 @@ export function shouldEmitHeader() {
     headerEmitted = true;
     return true;
 }
+/**
+ * Standing explanatory notes — artifact-family write-ups, capture-mode caveats,
+ * "a candidate is not a verdict" — are the same text on every call, and a trend
+ * tool gets called many times per investigation (8 times in one measured
+ * session). The information is worth stating; restating it is not. Returns true
+ * the FIRST time a key is seen in this server process and false thereafter, so
+ * a caller can print the long form once and a one-line pointer after that.
+ *
+ * Session-scoped on purpose, not per-snapshot: the reader is the same agent
+ * across snapshots, and re-teaching it the same caveat when it switches rungs is
+ * exactly the repetition being removed.
+ */
+const emittedNotes = new Set();
+export function shouldEmitNote(key) {
+    if (emittedNotes.has(key))
+        return false;
+    emittedNotes.add(key);
+    return true;
+}
+/** True if `key` has already been emitted, without marking it. */
+export function noteAlreadyEmitted(key) {
+    return emittedNotes.has(key);
+}
+/** Force the standing notes to print again (used by `repeat_notes`). */
+export function resetEmittedNotes() {
+    emittedNotes.clear();
+}
+const savedResults = new Map();
+export function setSavedResult(name, value, handle) {
+    savedResults.set(name, { value, handle });
+}
+export function getSavedResult(name) {
+    return savedResults.get(name);
+}
+export function listSavedResults() {
+    return [...savedResults.entries()].map(([name, r]) => ({
+        name,
+        handle: r.handle,
+    }));
+}
 function uniqueHandle(base) {
     // Sanitize to a short slug, then disambiguate against existing handles.
     const slug = base
@@ -87,14 +193,42 @@ function uniqueHandle(base) {
         i++;
     return `${slug}#${i}`;
 }
-export function getSnapshot() {
+/**
+ * The current snapshot.
+ *
+ * A LIGHT snapshot (loaded with `light: true`) has no dominator tree, no
+ * retained sizes and no shortest-path edges. On such a snapshot `retainedSize`
+ * reads 0 and `dominatorNode` / `pathEdge` are absent — which does not throw, it
+ * silently produces zeros and empty traces. A tool that reported those as
+ * results would be confidently wrong, which is worse than refusing.
+ *
+ * So light access is DENY-BY-DEFAULT and must be opted into per call site with
+ * `{allowLight: true}`, by tools that read only counts, names, types, self
+ * sizes, string values or edges. Enforcing it here rather than in the tool
+ * wrapper is deliberate: this is the one funnel every tool goes through,
+ * including tools dispatched in-process by `memlab_batch`, which bypass the
+ * guardrail wrapper entirely.
+ */
+export function getSnapshot(opts) {
     const entry = currentHandle ? loaded.get(currentHandle) : undefined;
     if (!entry) {
         throw new Error('No heap snapshot loaded. Use memlab_load_snapshot first.');
     }
+    if (entry.metadata.light && !opts?.allowLight) {
+        throw new Error(`Snapshot "${entry.metadata.handle}" was loaded in LIGHT mode, which skips the dominator/retained-size pass — this analysis needs it. ` +
+            'Light mode supports count / name / type / self-size / string queries only: memlab_class_histogram (with include_retained_size:false), memlab_search_nodes (without min_retained_size), memlab_search_strings, memlab_string_patterns, plus memlab_snapshot_header and memlab_snapshots, which do not read the graph. ' +
+            `Reload for full analysis: memlab_load_snapshot({file_path: "${entry.metadata.filePath}"}).`);
+    }
+    touch(currentHandle);
     instrumentSnapshot(entry.snapshot);
     return entry.snapshot;
 }
+/** True when the current snapshot was loaded without the dominator pass. */
+export function isLightSnapshot() {
+    if (!currentHandle)
+        return false;
+    return loaded.get(currentHandle)?.metadata.light === true;
+}
 export function getFilePath() {
     if (!currentHandle)
         return null;
@@ -125,17 +259,73 @@ export function setSnapshot(snapshot, filePath, metadata, opts = {}) {
     const replace = opts.replace ?? true;
     if (replace) {
         loaded.clear();
+        dropEvalScratch(null);
     }
     const handle = uniqueHandle(opts.alias || metadata.fileName);
-    const full = { handle, filePath, ...metadata };
+    const full = {
+        handle,
+        filePath,
+        ...metadata,
+        light: metadata.light === true,
+    };
     loaded.set(handle, { snapshot, metadata: full });
     currentHandle = handle;
+    touch(handle);
     headerEmitted = false;
     return full;
 }
 export function listSnapshots() {
     return [...loaded.values()].map(l => l.metadata);
 }
+/**
+ * Drop all resident snapshots and reset the current handle. Used to release the
+ * previous snapshot's memory BEFORE parsing a replacement, so peak RSS during a
+ * large load is one heap rather than two (avoids the GC death-spiral described
+ * in P2403258184 §3).
+ */
+export function clearAllSnapshots() {
+    loaded.clear();
+    lastUsed.clear();
+    dropEvalScratch(null);
+    currentHandle = null;
+    headerEmitted = false;
+}
+/**
+ * A resident snapshot loaded from this exact path, if any.
+ *
+ * The point of a snapshot cache is to not re-parse a file this process already
+ * has in memory; that check has to key on the resolved path, since the handle is
+ * derived from the file name and may have been disambiguated.
+ */
+export function findResidentByPath(filePath) {
+    for (const { metadata } of loaded.values()) {
+        if (metadata.filePath === filePath)
+            return metadata;
+    }
+    return null;
+}
+/**
+ * Drop every resident snapshot except `handle`, which becomes current.
+ *
+ * Used by the load cache-hit path so a hit is indistinguishable from a real load
+ * apart from speed: a replace-mode load unloads the others, and a hit must do
+ * the same or the two paths leave different state behind.
+ */
+export function retainOnlySnapshot(handle) {
+    if (!loaded.has(handle))
+        return false;
+    for (const h of [...loaded.keys()]) {
+        if (h === handle)
+            continue;
+        loaded.delete(h);
+        lastUsed.delete(h);
+        dropEvalScratch(h);
+    }
+    currentHandle = handle;
+    touch(handle);
+    headerEmitted = false;
+    return true;
+}
 export function getCurrentHandle() {
     return currentHandle;
 }
@@ -149,11 +339,16 @@ export function setCurrentSnapshot(handle) {
     if (!loaded.has(handle))
         return false;
     currentHandle = handle;
+    touch(handle);
     headerEmitted = false;
     return true;
 }
 export function removeSnapshot(handle) {
     const existed = loaded.delete(handle);
+    if (existed) {
+        lastUsed.delete(handle);
+        dropEvalScratch(handle);
+    }
     if (existed && currentHandle === handle) {
         currentHandle = loaded.size > 0 ? [...loaded.keys()][0] : null;
         headerEmitted = false;

package/dist/heap-state.js.map

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

package/dist/index.js

@@ -17,6 +17,7 @@ import { installAnalysisGuardrail } from './guardrail.js';
 // so the MCP server can return proper error responses to the client.
 config.errorHandling = ErrorHandling.Throw;
 import { registerLoadSnapshot } from './tools/load-snapshot.js';
+import { registerSnapshotHeader } from './tools/snapshot-header.js';
 import { registerSnapshotSummary } from './tools/snapshot-summary.js';
 import { registerLargestObjects } from './tools/largest-objects.js';
 import { registerGetNode } from './tools/get-node.js';
@@ -54,6 +55,7 @@ import { registerReferrerSummary } from './tools/referrer-summary.js';
 import { registerEventListenerLeaks } from './tools/event-listener-leaks.js';
 import { registerFindByShape } from './tools/find-by-shape.js';
 import { registerWeakMapEntries } from './tools/weakmap-entries.js';
+import { registerMapEntries } from './tools/map-entries.js';
 import { registerGetValue } from './tools/get-value.js';
 import { registerGetString } from './tools/get-string.js';
 import { registerSearchStrings } from './tools/search-strings.js';
@@ -66,16 +68,35 @@ import { registerGrowthSignals } from './tools/growth-signals.js';
 import { registerServerStatus } from './tools/server-status.js';
 import { registerDevArtifacts } from './tools/dev-artifacts.js';
 import { registerSequenceAnalysis } from './tools/sequence-analysis.js';
+import { registerLeakReport } from './tools/leak-report.js';
+import { registerMatchObject } from './tools/match-object.js';
+import { registerExplainDelta } from './tools/explain-delta.js';
+import { registerHypothesis } from './tools/hypothesis.js';
+import { registerLadder } from './tools/ladder.js';
+import { registerFindingIndex } from './tools/finding-index.js';
+import { registerAppHeap } from './tools/app-heap.js';
+import { registerHuntReport } from './tools/hunt-report.js';
 import { registerEventRegistry } from './tools/event-registry.js';
+import { registerDominatorChain } from './tools/dominator-chain.js';
+import { registerDuplicateObjects } from './tools/duplicate-objects.js';
+import { registerRetainerLayers } from './tools/retainer-layers.js';
+import { registerBatch } from './tools/batch.js';
+import { registerPopulationDiff } from './tools/population-diff.js';
+import { registerDominatorAttribution } from './tools/dominator-attribution.js';
+import { registerCollectionTrend } from './tools/collection-trend.js';
+import { registerVerifyFix } from './tools/verify-fix.js';
+import { registerToolsIndex } from './tools/tools-index.js';
+import { registerAnalyzeRun } from './tools/analyze-run.js';
 const server = new McpServer({
     name: 'memlab',
-    version: '2.12.0',
+    version: '2.52.0', // keep in sync with package.json
 });
 // Wrap every tool with a wall-clock guardrail (default 90s, override per-call
 // with timeout_ms or globally with MEMLAB_ANALYSIS_TIMEOUT_MS). Must run before
 // the tools are registered so their handlers are wrapped.
 installAnalysisGuardrail(server);
 registerLoadSnapshot(server);
+registerSnapshotHeader(server);
 registerSnapshotSummary(server);
 registerLargestObjects(server);
 registerGetNode(server);
@@ -111,6 +132,7 @@ registerReferrerSummary(server);
 registerEventListenerLeaks(server);
 registerFindByShape(server);
 registerWeakMapEntries(server);
+registerMapEntries(server);
 registerGetValue(server);
 registerGetString(server);
 registerSearchStrings(server);
@@ -125,7 +147,25 @@ registerGrowthSignals(server);
 registerServerStatus(server);
 registerDevArtifacts(server);
 registerSequenceAnalysis(server);
+registerLeakReport(server);
+registerMatchObject(server);
+registerExplainDelta(server);
+registerHypothesis(server);
+registerLadder(server);
+registerFindingIndex(server);
+registerAppHeap(server);
+registerHuntReport(server);
 registerEventRegistry(server);
+registerDominatorChain(server);
+registerDuplicateObjects(server);
+registerRetainerLayers(server);
+registerBatch(server);
+registerPopulationDiff(server);
+registerDominatorAttribution(server);
+registerCollectionTrend(server);
+registerVerifyFix(server);
+registerToolsIndex(server);
+registerAnalyzeRun(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAClE,OAAO,EAAC,oBAAoB,EAAC,MAAM,2CAA2C,CAAC;AAC/E,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,MAAM,EAAC,MAAM,EAAE,aAAa,EAAC,GAAG,UAAU,CAAC;AAC3C,OAAO,EAAC,wBAAwB,EAAC,MAAM,gBAAgB,CAAC;AAExD,qEAAqE;AACrE,qEAAqE;AACrE,MAAM,CAAC,aAAa,GAAG,aAAa,CAAC,KAAK,CAAC;AAE3C,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,eAAe,EAAC,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAC,wBAAwB,EAAC,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,yBAAyB,EAAC,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAC,wBAAwB,EAAC,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,wBAAwB,EAAC,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAC,yBAAyB,EAAC,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAC,sBAAsB,EAAC,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAC,eAAe,EAAC,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAC,eAAe,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,0BAA0B,EAAC,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAC,mBAAmB,EAAC,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAC,2BAA2B,EAAC,MAAM,iCAAiC,CAAC;AAC5E,OAAO,EAAC,2BAA2B,EAAC,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAC,4BAA4B,EAAC,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,wBAAwB,EAAC,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAC,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,kBAAkB,EAAC,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAC,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAC,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAC,eAAe,EAAC,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,wBAAwB,EAAC,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAC,4BAA4B,EAAC,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAC,uBAAuB,EAAC,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAC,kBAAkB,EAAC,MAAM,wBAAwB,CAAC;AAE1D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,QAAQ,EAAE,iCAAiC;CACrD,CAAC,CAAC;AAEH,8EAA8E;AAC9E,gFAAgF;AAChF,0DAA0D;AAC1D,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAEjC,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAClC,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAClC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACnC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACzB,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC1B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,YAAY,CAAC,MAAM,CAAC,CAAC;AACrB,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,2BAA2B,CAAC,MAAM,CAAC,CAAC;AACpC,2BAA2B,CAAC,MAAM,CAAC,CAAC;AACpC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC1B,4BAA4B,CAAC,MAAM,CAAC,CAAC;AACrC,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,cAAc,CAAC,MAAM,CAAC,CAAC;AACvB,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC7B,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAC9B,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,wBAAwB,CAAC,MAAM,CAAC,CAAC;AACjC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,aAAa,CAAC,MAAM,CAAC,CAAC;AACtB,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,4BAA4B,CAAC,MAAM,CAAC,CAAC;AACrC,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAChC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC1B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAE3B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/progress.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+export interface ProgressReporter {
+    /**
+     * Report entry into a phase. `step` is 1-based and `total` is the expected
+     * number of phases, so a host can render a determinate bar.
+     */
+    phase(step: number, total: number, message: string): void;
+}
+/**
+ * Build a reporter from a tool handler's `extra` argument.
+ *
+ * Tolerates a missing or empty `extra`: tools dispatched in-process by
+ * `memlab_batch` are called with `{}`, and a reporter that threw there would
+ * turn a progress nicety into a batch-wide failure.
+ */
+export declare function makeProgressReporter(extra: unknown, label: string): ProgressReporter;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3D;AASD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAsBlB"}

package/dist/progress.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+const NOOP = {
+    phase: () => {
+        // No progress channel and no stderr labelling to do for a caller that
+        // supplied no `extra` (in-process dispatch); reporting is simply off.
+    },
+};
+/**
+ * Build a reporter from a tool handler's `extra` argument.
+ *
+ * Tolerates a missing or empty `extra`: tools dispatched in-process by
+ * `memlab_batch` are called with `{}`, and a reporter that threw there would
+ * turn a progress nicety into a batch-wide failure.
+ */
+export function makeProgressReporter(extra, label) {
+    if (extra == null || typeof extra !== 'object')
+        return NOOP;
+    const e = extra;
+    const token = e._meta?.progressToken;
+    const send = typeof e.sendNotification === 'function' ? e.sendNotification : null;
+    return {
+        phase(step, total, message) {
+            process.stderr.write(`[${label} ${step}/${total}] ${message}\n`);
+            if (send == null || token == null)
+                return;
+            // Fire-and-forget: a client that cannot accept the notification must not
+            // fail the operation the notification is about.
+            void send({
+                method: 'notifications/progress',
+                params: { progressToken: token, progress: step, total, message },
+            }).catch(() => {
+                // Swallowed on purpose: a client that rejects the notification must not
+                // fail the operation the notification is merely describing.
+            });
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6CH,MAAM,IAAI,GAAqB;IAC7B,KAAK,EAAE,GAAG,EAAE;QACV,sEAAsE;QACtE,sEAAsE;IACxE,CAAC;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,KAAa;IAEb,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,CAAC,GAAG,KAA6B,CAAC;IACxC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC;IACrC,MAAM,IAAI,GACR,OAAO,CAAC,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvE,OAAO;QACL,KAAK,CAAC,IAAY,EAAE,KAAa,EAAE,OAAe;YAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC;YACjE,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI;gBAAE,OAAO;YAC1C,yEAAyE;YACzE,gDAAgD;YAChD,KAAK,IAAI,CAAC;gBACR,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE,EAAC,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAC;aAC/D,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACZ,wEAAwE;gBACxE,4DAA4D;YAC9D,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/result-handles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+export declare function resolveSavedNodeIds(name: string): number[];
+//# sourceMappingURL=result-handles.d.ts.map

package/dist/result-handles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-handles.d.ts","sourceRoot":"","sources":["../src/result-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA+C1D"}

package/dist/result-handles.js

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { getEvalScratch } from './heap-state.js';
+/**
+ * Read a saved result (from `memlab_eval`'s `save_as` / `helpers.save`) as a
+ * node-id list, so one tool's output can feed another's input without the ids
+ * making a round trip through the transcript.
+ *
+ * A list of a few thousand ids is tens of thousands of tokens to print and
+ * re-type, and re-typing them is where they get truncated or corrupted. The
+ * scratch store already existed for `eval`; this makes it readable by the tools
+ * that take `node_ids`, which is where such a list is actually wanted.
+ *
+ * Accepts the shapes a result realistically has: an array of numbers, an array
+ * of `{id}` objects, or an object with an `ids`/`node_ids` array.
+ */
+// `memlab_eval` namespaces saved values in the shared per-snapshot scratch so
+// they cannot collide with its own indexes. Reading them back means honoring
+// that prefix — a bare-name lookup finds nothing and reports "not saved" for a
+// result that is sitting right there.
+const SAVED_PREFIX = '__saved:';
+export function resolveSavedNodeIds(name) {
+    const scratch = getEvalScratch();
+    const prefixed = SAVED_PREFIX + name;
+    const key = prefixed in scratch ? prefixed : name;
+    if (!(key in scratch)) {
+        const available = Object.keys(scratch)
+            .filter(k => k.startsWith(SAVED_PREFIX))
+            .map(k => k.slice(SAVED_PREFIX.length));
+        throw new Error(`No saved result named "${name}". ` +
+            (available.length > 0
+                ? `Saved: ${available.join(', ')}.`
+                : 'Nothing is saved for this snapshot. Save one with memlab_eval({code, save_as: "name"}).') +
+            ' Saved results are per-snapshot and are dropped when the snapshot is replaced.');
+    }
+    const raw = scratch[key];
+    const fromArray = (arr) => {
+        const ids = [];
+        for (const item of arr) {
+            if (typeof item === 'number' && Number.isFinite(item)) {
+                ids.push(item);
+            }
+            else if (item != null && typeof item === 'object' && 'id' in item) {
+                const id = item.id;
+                if (typeof id === 'number')
+                    ids.push(id);
+            }
+        }
+        return ids;
+    };
+    let ids = [];
+    if (Array.isArray(raw)) {
+        ids = fromArray(raw);
+    }
+    else if (raw != null && typeof raw === 'object') {
+        const obj = raw;
+        const arr = Array.isArray(obj.ids)
+            ? obj.ids
+            : Array.isArray(obj.node_ids)
+                ? obj.node_ids
+                : null;
+        if (arr != null)
+            ids = fromArray(arr);
+    }
+    if (ids.length === 0) {
+        throw new Error(`Saved result "${name}" holds no node ids. Expected an array of ids, an array of objects with an \`id\` field, or an object with an \`ids\` array.`);
+    }
+    return ids;
+}
+//# sourceMappingURL=result-handles.js.map

package/dist/result-handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-handles.js","sourceRoot":"","sources":["../src/result-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,sCAAsC;AACtC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;aACnC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,KAAK;YACjC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;gBACnB,CAAC,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACnC,CAAC,CAAC,yFAAyF,CAAC;YAC9F,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAY,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,CAAC,GAAc,EAAY,EAAE;QAC7C,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;YACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;iBAAM,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACpE,MAAM,EAAE,GAAI,IAAuB,CAAC,EAAE,CAAC;gBACvC,IAAI,OAAO,EAAE,KAAK,QAAQ;oBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,IAAI,GAAG,GAAa,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;SAAM,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,GAA0C,CAAC;QACvD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAChC,CAAC,CAAC,GAAG,CAAC,GAAG;YACT,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAC3B,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACd,CAAC,CAAC,IAAI,CAAC;QACX,IAAI,GAAG,IAAI,IAAI;YAAE,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,8HAA8H,CACpJ,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/string-index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { IHeapNode, IHeapSnapshot } from '@memlab/core';
+/**
+ * Per-value string duplication stats: how many copies, what they cost, and a
+ * bounded sample of node ids to follow up on.
+ */
+export interface StringDupStats {
+    count: number;
+    totalSize: number;
+    exampleIds: number[];
+    /**
+     * Copies reachable ONLY through a dev/automation root. -1 when the index was
+     * built without the dev-root pass (see {@link buildStringIndex}).
+     */
+    devOnlyCount: number;
+}
+export interface StringIndex {
+    byValue: Map<string, StringDupStats>;
+    /** True when `devOnlyCount` is populated. */
+    hasDevOnly: boolean;
+    concatStringCount: number;
+    concatStringSize: number;
+}
+/**
+ * Build (or reuse) the per-value string duplication index for a snapshot.
+ *
+ * `memlab_duplicated_strings` and `memlab_intern_opportunities` were each doing
+ * their own full pass over every string node to build the same value → {count,
+ * size, ids} map, and both are commonly run back to back on the same snapshot —
+ * so the second one re-walked millions of nodes to recompute what the first had
+ * already produced. The scan is cached in the per-snapshot eval scratch, which
+ * already has exactly the lifecycle this needs: keyed by the active handle, and
+ * dropped when that snapshot is replaced or unloaded, so a stale index can never
+ * outlive the graph its node ids refer to.
+ *
+ * `withDevOnly` gates the dev/automation reachability pass, which is a whole-
+ * graph walk that only `intern_opportunities` needs. A cached index built
+ * without it is UPGRADED (rebuilt once) rather than silently returned, since
+ * `devOnlyCount: -1` would otherwise be read as "no dev-only copies".
+ */
+export declare function buildStringIndex(snapshot: IHeapSnapshot, opts?: {
+    withDevOnly?: boolean;
+    isDevOnlyNode?: (node: IHeapNode) => boolean;
+}): StringIndex;
+/** True when this snapshot's string index is already built and resident. */
+export declare function stringIndexIsCached(): boolean;
+//# sourceMappingURL=string-index.d.ts.map

package/dist/string-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-index.d.ts","sourceRoot":"","sources":["../src/string-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAG3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;CACzC,GACL,WAAW,CAoDb;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}