@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/retainer-diff.js

@@ -0,0 +1,168 @@
+/**
+ * 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 { z } from 'zod';
+import { getCurrentHandle, getMetadataByHandle, getSnapshotByHandle, listSnapshots, } from '../heap-state.js';
+import { clusterByRetainerPath, renderClusterChain, selectPopulation, } from './trace-all.js';
+import { errorResult, formatNumber, markdownTable, toolResult, } from '../utils.js';
+export function registerRetainerDiff(server) {
+    server.tool('memlab_retainer_diff', 'A population grew between two snapshots — did it grow along the SAME retention path, or did a new one appear?\n\n' +
+        'This is the question a count diff cannot answer and the one that decides what to fix. "42,000 → 61,000 listener records" is consistent with two completely different bugs: an existing owner accumulating faster, or a second owner that did not exist before. A count, a class histogram and a population diff all read identically in the two cases.\n\n' +
+        'Clusters the full population by retainer path in BOTH snapshots and reports paths that are new, grew, shrank or vanished. Both snapshots must be resident (load with `keep_previous: true`); the active snapshot is not changed.', {
+        before_handle: z
+            .string()
+            .describe('Handle of the earlier snapshot (memlab_snapshots lists them).'),
+        after_handle: z.string().describe('Handle of the later snapshot.'),
+        class_name: z
+            .string()
+            .optional()
+            .describe('Population: every instance of this class.'),
+        shape: z
+            .array(z.string())
+            .optional()
+            .describe('Population: every object carrying ALL of these properties — the selector that survives minification, and the one to use here since node ids and class names are not comparable across captures.'),
+        framework_filter: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Collapse V8/framework internals out of the path signature so structurally identical application paths compare equal (default true).'),
+        limit: z
+            .number()
+            .optional()
+            .default(10)
+            .describe('Rows in the change table (default 10).'),
+        max_depth: z
+            .number()
+            .optional()
+            .describe('Compare on the first N hops from the GC ROOT instead of the whole path. Defaults to the whole path; use 5-7 when the full-depth signature fragments into roughly one path per object (a per-chat property edge or a per-event listener array does that), which otherwise makes every path look new or vanished.'),
+        max_trace: z
+            .number()
+            .optional()
+            .default(200000)
+            .describe('Per-snapshot bound on nodes traced (default 200,000).'),
+    }, async ({ before_handle, after_handle, class_name, shape, framework_filter, limit, max_depth, max_trace, }) => {
+        try {
+            if ((class_name == null) === (shape == null || shape.length === 0)) {
+                return errorResult(new Error('Pass exactly one of class_name / shape. Node ids are per-capture and cannot select a population in two snapshots, which is why node_ids is not accepted here.'));
+            }
+            const resolve = (h) => {
+                const snap = getSnapshotByHandle(h);
+                const meta = getMetadataByHandle(h);
+                if (snap == null || meta == null) {
+                    const available = listSnapshots()
+                        .map(m => m.handle)
+                        .join(', ');
+                    throw new Error(`No resident snapshot with handle "${h}". Resident: ${available === '' ? '(none)' : available}. Load both rungs with memlab_load_snapshot({keep_previous: true}).`);
+                }
+                if (meta.light) {
+                    throw new Error(`Snapshot "${h}" was loaded with light: true, which skips the path/dominator pass — there are no retainer paths to compare. Reload it with light: false.`);
+                }
+                return { snap, meta };
+            };
+            const before = resolve(before_handle);
+            const after = resolve(after_handle);
+            if (before_handle === after_handle) {
+                return errorResult(new Error('before_handle and after_handle are the same snapshot.'));
+            }
+            const sel = { className: class_name, shape };
+            const b = clusterByRetainerPath(selectPopulation(before.snap, sel), framework_filter, max_trace, max_depth);
+            const a = clusterByRetainerPath(selectPopulation(after.snap, sel), framework_filter, max_trace, max_depth);
+            if (b.clusters.length === 0 && a.clusters.length === 0) {
+                return toolResult('The population is empty (or unreachable) in both snapshots — nothing to compare. Check the selector with `memlab_class_histogram` / `memlab_shape_histogram` on each handle.');
+            }
+            const beforeByKey = new Map(b.clusters.map(c => [c.key, c]));
+            const afterByKey = new Map(a.clusters.map(c => [c.key, c]));
+            const rows = [];
+            for (const key of new Set([
+                ...beforeByKey.keys(),
+                ...afterByKey.keys(),
+            ])) {
+                const bc = beforeByKey.get(key);
+                const ac = afterByKey.get(key);
+                const representative = ac ?? bc;
+                if (representative == null)
+                    continue;
+                const beforeCount = bc?.count ?? 0;
+                const afterCount = ac?.count ?? 0;
+                if (beforeCount === afterCount)
+                    continue;
+                rows.push({
+                    key,
+                    before: beforeCount,
+                    after: afterCount,
+                    delta: afterCount - beforeCount,
+                    chain: renderClusterChain(representative.steps),
+                    exampleAfter: ac?.exampleIds[0] ?? null,
+                });
+            }
+            rows.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+            const bTotal = b.traced;
+            const aTotal = a.traced;
+            const label = class_name != null
+                ? `class \`${class_name}\``
+                : `shape \`{${(shape ?? []).join(', ')}}\``;
+            const lines = [
+                `## Retention paths for ${label}: ${before.meta.fileName} → ${after.meta.fileName}`,
+                '',
+                `Population: **${formatNumber(bTotal)} → ${formatNumber(aTotal)}** traced objects (${aTotal - bTotal >= 0 ? '+' : ''}${formatNumber(aTotal - bTotal)}), across **${formatNumber(b.clusters.length)} → ${formatNumber(a.clusters.length)}** distinct paths.`,
+            ];
+            if (b.truncated || a.truncated) {
+                lines.push('', `⚠ The ${formatNumber(max_trace)}-node trace bound was hit in ${b.truncated && a.truncated ? 'both snapshots' : b.truncated ? 'the BEFORE snapshot' : 'the AFTER snapshot'}, so the counts below are of a partial sweep and the two sides may not be comparable. Raise \`max_trace\`.`);
+            }
+            if (max_depth == null &&
+                Math.max(b.clusters.length, a.clusters.length) >
+                    Math.max(bTotal, aTotal) * 0.5) {
+                lines.push('', `⚠ ${formatNumber(a.clusters.length)} paths for ${formatNumber(aTotal)} objects — the full-depth signature is keying on a per-instance hop, so paths do not line up across captures and almost everything below will read as new or vanished. Re-run with \`max_depth: 5\` (or 6-7) to compare owners rather than instances.`);
+            }
+            if (rows.length === 0) {
+                lines.push('', '**Every path holds exactly the same count in both snapshots.** The population did not change along any retention path — if a total did change, it changed somewhere this selector does not cover.');
+                return toolResult(lines.join('\n'));
+            }
+            const newPaths = rows.filter(r => r.before === 0);
+            const grown = rows.filter(r => r.before > 0 && r.delta > 0);
+            const gone = rows.filter(r => r.after === 0);
+            lines.push('', newPaths.length > 0
+                ? `**${formatNumber(newPaths.length)} path(s) are NEW**, holding ${formatNumber(newPaths.reduce((s, r) => s + r.after, 0))} object(s) that had no counterpart in the earlier snapshot. A new path is a different bug from an existing one accumulating: the owner did not exist before, so a fix aimed at the pre-existing owner will not touch it.`
+                : `**No new paths.** All of the change is existing owners holding more or fewer objects, so the retention MECHANISM is unchanged and the question is what is driving the rate.`);
+            if (grown.length > 0 && newPaths.length > 0) {
+                lines.push('', `${formatNumber(grown.length)} pre-existing path(s) also grew, by ${formatNumber(grown.reduce((s, r) => s + r.delta, 0))} object(s) in total — both mechanisms are active, so sizing a fix against either one alone will over-promise.`);
+            }
+            lines.push('', markdownTable(['Change', 'Before', 'After', 'Δ', 'Example'], rows
+                .slice(0, limit)
+                .map(r => [
+                r.before === 0
+                    ? 'NEW'
+                    : r.after === 0
+                        ? 'gone'
+                        : r.delta > 0
+                            ? 'grew'
+                            : 'shrank',
+                formatNumber(r.before),
+                formatNumber(r.after),
+                `${r.delta >= 0 ? '+' : ''}${formatNumber(r.delta)}`,
+                r.exampleAfter != null ? `@${r.exampleAfter}` : '—',
+            ]), new Set([1, 2, 3])));
+            if (rows.length > limit) {
+                lines.push('', `_${formatNumber(rows.length - limit)} further changed path(s) not shown; raise \`limit\`._`);
+            }
+            rows.slice(0, Math.min(limit, 5)).forEach((r, i) => {
+                lines.push('', `### ${i + 1}. ${r.before === 0 ? 'NEW' : r.after === 0 ? 'gone' : r.delta > 0 ? 'grew' : 'shrank'} ${formatNumber(r.before)} → ${formatNumber(r.after)}`, '', r.chain);
+            });
+            if (gone.length > 0) {
+                lines.push('', `_${formatNumber(gone.length)} path(s) present before and absent after (${formatNumber(gone.reduce((s, x) => s + x.before, 0))} objects). That is usually a genuine release, but it is also what a differently-shaped path looks like after a code change renamed something in it — the signature includes class names._`);
+            }
+            lines.push('', '_Paths are matched by structural signature, so a rename anywhere along a chain reads as one path vanishing and another appearing. Bytes are not compared here — use `memlab_what_if` on a cluster for what a fix at one owner would free._', '', `Active snapshot unchanged (${getCurrentHandle() ?? 'none'}).`);
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=retainer-diff.js.map

package/dist/tools/retainer-diff.js.map

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

package/dist/tools/retainer-layers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { IHeapSnapshot } from '@memlab/core';
+/**
+ * Reachability from the synthetic GC roots with one node treated as a sink:
+ * `blocked` is marked reached (so it is not reported as unreachable) but its
+ * outgoing edges are never followed. Anything left unmarked is reachable ONLY
+ * through `blocked`, i.e. it lives inside that node's retained subtree.
+ *
+ * Mirrors `computeReachableWithoutDevRoots` in dev-artifacts.ts, which does the
+ * same walk with the dev/automation roots as sinks.
+ */
+export declare function computeReachableWithoutNode(snapshot: IHeapSnapshot, blockedId: number): Uint8Array;
+export declare function registerRetainerLayers(server: McpServer): void;
+//# sourceMappingURL=retainer-layers.d.ts.map

package/dist/tools/retainer-layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retainer-layers.d.ts","sourceRoot":"","sources":["../../src/tools/retainer-layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAuB,aAAa,EAAC,MAAM,cAAc,CAAC;AAatE;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,GAChB,UAAU,CAmBZ;AAqBD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6K9D"}

package/dist/tools/retainer-layers.js

@@ -0,0 +1,179 @@
+/**
+ * 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 { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { errorResult, formatBytes, formatNumber, isNodeWorthInspecting, markdownTable, toolResult, truncateNodeName, } from '../utils.js';
+/**
+ * Reachability from the synthetic GC roots with one node treated as a sink:
+ * `blocked` is marked reached (so it is not reported as unreachable) but its
+ * outgoing edges are never followed. Anything left unmarked is reachable ONLY
+ * through `blocked`, i.e. it lives inside that node's retained subtree.
+ *
+ * Mirrors `computeReachableWithoutDevRoots` in dev-artifacts.ts, which does the
+ * same walk with the dev/automation roots as sinks.
+ */
+export function computeReachableWithoutNode(snapshot, blockedId) {
+    const reached = new Uint8Array(snapshot.nodes.length);
+    const stack = [];
+    snapshot.nodes.forEach((node) => {
+        if (node.type !== 'synthetic' && node.id > 3)
+            return;
+        if (reached[node.nodeIndex])
+            return;
+        reached[node.nodeIndex] = 1;
+        if (node.id !== blockedId)
+            stack.push(node);
+    });
+    while (stack.length > 0) {
+        const node = stack.pop();
+        node.forEachReference((edge) => {
+            const to = edge.toNode;
+            if (reached[to.nodeIndex])
+                return;
+            reached[to.nodeIndex] = 1;
+            if (to.id !== blockedId)
+                stack.push(to);
+        });
+    }
+    return reached;
+}
+function groupKey(g) {
+    return `${g.fromType}\u0000${g.fromName}\u0000${g.edgeType}\u0000${g.edgeName}`;
+}
+export function registerRetainerLayers(server) {
+    server.tool('memlab_retainer_layers', 'Counterfactual retainer analysis: answer "if I cut this edge, would the object still be retained, and by what?". ' +
+        "Enumerates the INDEPENDENT retaining edges into a node — the incoming edges whose source is still reachable from a GC root when the target itself is treated as a sink — so back-edges from inside the target's own retained subtree are excluded. " +
+        'The object becomes unreachable only when ALL independent retainers are cut, so a count above 1 means any single fix leaves it retained by the others. ' +
+        'Use this BEFORE writing a fix: memlab_retainer_trace and memlab_detached_dom --group_by retainer each report ONE path/grouping, which is why a stack of caches holding the same object looks like a single retainer and a partial fix reports a misleading win. ' +
+        'Complements memlab_dominator_chain (accountability chain upward) and memlab_retainer_trace (one shortest path).', {
+        node_id: z
+            .number()
+            .int()
+            .describe('The numeric ID of the heap node to analyze'),
+        max_retainers: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(20)
+            .describe('Maximum number of distinct retainer groups to list (default 20). Grouping is by (source class, source type, edge name, edge type).'),
+    }, async ({ node_id, max_retainers }) => {
+        try {
+            const snapshot = getSnapshot();
+            const target = snapshot.getNodeById(node_id);
+            if (!target) {
+                return errorResult(`Node with id ${node_id} not found`);
+            }
+            const reached = computeReachableWithoutNode(snapshot, target.id);
+            // Partition incoming edges into independent retainers (source still
+            // reachable with the target blocked) and internal back-edges (source
+            // only reachable through the target).
+            const groups = new Map();
+            let independentEdgeCount = 0;
+            let backEdgeCount = 0;
+            for (const edge of target.referrers) {
+                const from = edge.fromNode;
+                // A self-edge (V8 emits them for DOM nodes) cannot retain the target,
+                // but the sink walk marks the target itself reached so it would
+                // otherwise pass the test below. Count it with the back-edges.
+                if (from.id === target.id || !reached[from.nodeIndex]) {
+                    backEdgeCount++;
+                    continue;
+                }
+                independentEdgeCount++;
+                const g = {
+                    fromName: from.name,
+                    fromType: from.type,
+                    edgeName: String(edge.name_or_index),
+                    edgeType: edge.type,
+                };
+                const key = groupKey(g);
+                const existing = groups.get(key);
+                if (existing) {
+                    existing.count++;
+                    if (from.retainedSize > existing.maxRetained) {
+                        existing.maxRetained = from.retainedSize;
+                        existing.exampleFromId = from.id;
+                    }
+                }
+                else {
+                    groups.set(key, {
+                        ...g,
+                        count: 1,
+                        exampleFromId: from.id,
+                        maxRetained: from.retainedSize,
+                    });
+                }
+            }
+            const sorted = [...groups.values()].sort((a, b) => b.maxRetained - a.maxRetained || b.count - a.count);
+            const shown = sorted.slice(0, max_retainers);
+            const targetLabel = truncateNodeName(target.name, target.type, target.self_size, 60);
+            const lines = [
+                `## Retainer layers for @${target.id} (${targetLabel})`,
+                '',
+                `Retained ${formatBytes(target.retainedSize)}. ` +
+                    `${formatNumber(independentEdgeCount)} independent retaining edge(s) in ${formatNumber(sorted.length)} group(s)` +
+                    (backEdgeCount > 0
+                        ? `; ${formatNumber(backEdgeCount)} back-edge(s) from inside its own retained subtree excluded.`
+                        : '.'),
+                '',
+            ];
+            if (independentEdgeCount === 0) {
+                lines.push(target.type === 'synthetic' || target.id <= 3
+                    ? '**This node is a GC root itself** — it has no external retainer to cut.'
+                    : "**No independent retainer found.** Nothing outside this object's own subtree references it, so it is already GC-eligible (or reachable only via weak references). It should not be counted toward a leak total — see `memlab_detached_dom --only_with_retainer_path`.");
+                return toolResult(lines.join('\n'));
+            }
+            // The counterfactual verdict. Cutting one independent edge cannot change
+            // the reachability of any other independent source, because every such
+            // source is reachable on a path that does not pass through the target.
+            if (independentEdgeCount === 1) {
+                const only = sorted[0];
+                lines.push(`**Sole retainer — cutting it frees the object.** \`${only.edgeName}\` (${only.edgeType}) from @${only.exampleFromId} ${only.fromName} (${only.fromType}). ` +
+                    `Fixing this one reference reclaims ${formatBytes(target.retainedSize)}.`, '');
+            }
+            else {
+                lines.push(`**${formatNumber(independentEdgeCount)} independent retainers — cutting any ONE leaves the object retained by the other ${formatNumber(independentEdgeCount - 1)}.** ` +
+                    'A fix that removes a single one of these will show little or no memory win, and a before/after measurement that attributes the whole object to the removed retainer will overstate the result. ' +
+                    'All of them must be cut to reclaim the object.', '');
+            }
+            lines.push(markdownTable(['#', 'edges', 'from', 'edge', 'example', 'source retains'], shown.map((g, i) => [
+                String(i + 1),
+                formatNumber(g.count),
+                `${g.fromName} (${g.fromType})`,
+                `${g.edgeName} (${g.edgeType})`,
+                `@${g.exampleFromId}`,
+                formatBytes(g.maxRetained),
+            ])));
+            if (sorted.length > shown.length) {
+                lines.push('', `_${formatNumber(sorted.length - shown.length)} more retainer group(s) not shown — raise max_retainers to see them._`);
+            }
+            // A dominator that is not the GC-roots super-node means every path to
+            // the target passes through it, so it is a single choke point even when
+            // several independent edges exist.
+            const dom = target.dominatorNode;
+            if (independentEdgeCount > 1 &&
+                dom &&
+                dom.id !== target.id &&
+                dom.name !== '(GC roots)' &&
+                isNodeWorthInspecting(dom)) {
+                lines.push('', `**Single choke point:** every path still passes through the immediate dominator @${dom.id} ${truncateNodeName(dom.name, dom.type, dom.self_size, 60)} (retains ${formatBytes(dom.retainedSize)}). ` +
+                    'Cutting there frees the target in one change instead of cutting each retainer. Use `memlab_dominator_chain` to walk further up.');
+            }
+            lines.push('', '_Independence test: an incoming edge counts only if its source is still reachable from a GC root when the target is treated as a sink. ' +
+                "Edges failing that test originate inside the target's own retained subtree and cannot keep it alive._");
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=retainer-layers.js.map

package/dist/tools/retainer-layers.js.map

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

package/dist/tools/retainer-summary.d.ts

@@ -8,5 +8,23 @@
  * @oncall memory_lab
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { IHeapNode } from '@memlab/core';
+export interface TraceStep {
+    name: string;
+    type: string;
+    edgeName?: string;
+}
+export declare function getRetainerTrace(node: IHeapNode): TraceStep[] | null;
+export declare function traceToKey(steps: TraceStep[], frameworkFilter: boolean): string;
+/**
+ * Shorten one hop's label without changing which node it names.
+ *
+ * Order matters: elide C++ template arguments FIRST (that is where the bytes
+ * are and the elision is information-preserving about the outer type), and only
+ * then fall back to a blunt truncation.
+ */
+export declare function shortenPath(name: string): string;
+export declare function formatTraceChain(steps: TraceStep[]): string;
+export declare const COMPACT_GAP_MARKER = "\u22EF";
 export declare function registerRetainerSummary(server: McpServer): void;
 //# sourceMappingURL=retainer-summary.d.ts.map

package/dist/tools/retainer-summary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retainer-summary.d.ts","sourceRoot":"","sources":["../../src/tools/retainer-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA2IvE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuX/D"}
+{"version":3,"file":"retainer-summary.d.ts","sourceRoot":"","sources":["../../src/tools/retainer-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAC,SAAS,EAAY,MAAM,cAAc,CAAC;AAcvD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA6BD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,IAAI,CAuBpE;AAmBD,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAAE,EAClB,eAAe,EAAE,OAAO,GACvB,MAAM,CAaR;AAiBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBhD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAe3D;AAKD,eAAO,MAAM,kBAAkB,WAAM,CAAC;AAgDtC,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4d/D"}