@memlab/mcp-server 2.3.0 → 2.52.0

package/dist/tools/app-heap.js

@@ -0,0 +1,140 @@
+/**
+ * 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, getSnapshotMetadata } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+import { classifyArtifact } from '../artifact-classes.js';
+import { collectDevRoots, computeReachableWithoutDevRoots, } from './dev-artifacts.js';
+/**
+ * How much of this heap is actually the APPLICATION?
+ *
+ * A dev-build heap is mostly not the app. Measured on one WhatsApp Web capture:
+ * `system / ExternalStringData` — the bundle's own source text — was 56% of a
+ * 311 MB heap, single strings in it retained 84.9 / 22.5 / 17.8 / 10.2 MB, and
+ * code-related memory came to roughly two thirds of the total. So "drive to
+ * 600 MB" is mostly an instruction to load more bundle, the number is not
+ * comparable to production, and a threshold expressed against it is measuring
+ * the wrong thing.
+ *
+ * The split below is deliberately coarse and named, not a single magic number:
+ * a reader has to be able to see WHICH bucket dominates, because that is what
+ * decides whether the capture is usable at all.
+ */
+const CODE_TYPES = new Set(['code']);
+// Bundle source text and the V8 structures that hold it. These exist because
+// the app was *loaded*, not because it did anything.
+const BUNDLE_NAME_RE = /ExternalStringData|InstructionStream|BytecodeArray|SharedFunctionInfo|ScopeInfo|UncompiledData|FeedbackVector|FeedbackMetadata|FeedbackCell|ClosureFeedbackCellArray|\(constant pool\)|ConstantPool/;
+export function registerAppHeap(server) {
+    server.tool('memlab_app_heap', 'Report APP-ATTRIBUTABLE heap: total self size minus bundle/code memory, minus dev-build artifacts, minus measurement-harness content — the part of the heap that is actually the application. ' +
+        'On a dev build the raw number is mostly not the app: a measured WhatsApp Web capture had bundle source text (`system / ExternalStringData`) at 56% of a 311 MB heap and code-related memory at roughly two thirds of the total. A leak-hunt threshold expressed against the raw total therefore mostly measures how much bundle has loaded, and is not comparable to production at all. ' +
+        'Use this as the number to drive a hunt against and to quote in a report; use memlab_leak_report for whether anything is actually growing.', {
+        show_breakdown: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Show the per-bucket table (default true). The breakdown is the point — which bucket dominates decides whether the capture is usable.'),
+    }, async ({ show_breakdown }) => {
+        try {
+            const snapshot = getSnapshot();
+            const meta = getSnapshotMetadata();
+            const devRoots = collectDevRoots(snapshot);
+            const reached = devRoots.byId.size > 0
+                ? computeReachableWithoutDevRoots(snapshot, devRoots)
+                : null;
+            let total = 0;
+            let code = 0;
+            let bundle = 0;
+            let devOnly = 0;
+            let artifact = 0;
+            let app = 0;
+            let appNodes = 0;
+            const isDevOnly = (node) => reached != null && reached[node.nodeIndex] === 0;
+            snapshot.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                const size = node.self_size;
+                total += size;
+                // Precedence matters: a node is counted once, in the most specific
+                // bucket that explains why it is NOT app memory.
+                if (isDevOnly(node)) {
+                    devOnly += size;
+                    return;
+                }
+                if (CODE_TYPES.has(node.type)) {
+                    code += size;
+                    return;
+                }
+                if (BUNDLE_NAME_RE.test(node.name)) {
+                    bundle += size;
+                    return;
+                }
+                if (classifyArtifact(node.name) != null) {
+                    artifact += size;
+                    return;
+                }
+                app += size;
+                appNodes++;
+            });
+            const pct = (n) => total > 0 ? `${((n / total) * 100).toFixed(1)}%` : '—';
+            const lines = [
+                '## App-attributable heap',
+                '',
+                `**${formatBytes(app)} of ${formatBytes(total)} (${pct(app)}) is application memory** across ${formatNumber(appNodes)} nodes` +
+                    (meta ? ` in \`${meta.fileName}\`` : '') +
+                    '.',
+                '',
+            ];
+            if (show_breakdown) {
+                lines.push(markdownTable(['Bucket', 'Self size', '% of heap', 'What it is'], [
+                    [
+                        'App',
+                        formatBytes(app),
+                        pct(app),
+                        'The number to drive and report',
+                    ],
+                    [
+                        'Bundle / source text',
+                        formatBytes(bundle),
+                        pct(bundle),
+                        'Loaded, not allocated by use; absent at this scale in prod',
+                    ],
+                    [
+                        'Code / bytecode',
+                        formatBytes(code),
+                        pct(code),
+                        'JIT + compiled code; grows by exercising new paths',
+                    ],
+                    [
+                        'Dev/automation-retained',
+                        formatBytes(devOnly),
+                        pct(devOnly),
+                        'Held only via inspector/dev roots; GC-eligible in prod',
+                    ],
+                    [
+                        'Known artifacts',
+                        formatBytes(artifact),
+                        pct(artifact),
+                        'CDP/a11y/warmup families',
+                    ],
+                ], new Set([1, 2])), '');
+            }
+            const nonApp = total - app;
+            if (total > 0 && nonApp / total > 0.5) {
+                lines.push(`> ⚠️ **${pct(nonApp)} of this heap is not the application.** A threshold expressed against the raw total is mostly measuring how much bundle and code has loaded. Drive against the app-attributable figure above, and do not compare the raw total to production.`);
+            }
+            lines.push('', '_Buckets are mutually exclusive and sum to the total; each node lands in the most specific bucket that explains why it is not app memory. Self size, not retained: retained sizes overlap and would not sum._');
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=app-heap.js.map

package/dist/tools/app-heap.js.map

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

package/dist/tools/auto-investigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-investigate.d.ts","sourceRoot":"","sources":["../../src/tools/auto-investigate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAm9CvE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAirB/D"}
+{"version":3,"file":"auto-investigate.d.ts","sourceRoot":"","sources":["../../src/tools/auto-investigate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA49CvE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0tB/D"}

package/dist/tools/auto-investigate.js

@@ -11,7 +11,7 @@ import memlabCore from '@memlab/core';
 const { utils, NumericSet } = memlabCore;
 import { z } from 'zod';
 import { getSnapshot, getSnapshotMetadata } from '../heap-state.js';
-import { filterLargestObjects, isNodeWorthInspecting, formatBytes, formatNumber, truncateNodeName, instrumentationRetainerNote, errorResult, toolResult, suggestionsSuppressed, } from '../utils.js';
+import { filterLargestObjects, isNodeWorthInspecting, formatBytes, formatNumber, formatRetainerTree, truncateNodeName, instrumentationRetainerNote, errorResult, toolResult, suggestionsSuppressed, } from '../utils.js';
 function classifySeverity(retainedSize, totalSize) {
     if (totalSize === 0)
         return 'LOW';
@@ -598,22 +598,31 @@ function formatTrace(trace, maxSteps) {
             continue;
         collapsed.push(step);
     }
-    const shown = collapsed.length <= maxSteps
-        ? collapsed
-        : [...collapsed.slice(0, 3), ...collapsed.slice(-2)];
-    const parts = [];
-    for (let i = 0; i < shown.length; i++) {
-        const s = shown[i];
-        const name = truncateNodeName(s.name, s.type, s.selfSize, 50);
-        parts.push(`@${s.nodeId} ${name} (${s.type}) [${formatBytes(s.retainedSize)}]`);
-        if (i === 2 && collapsed.length > maxSteps) {
-            parts.push(`  … ${collapsed.length - 5} more nodes …`);
-        }
-        if (i < shown.length - 1 && s.edgeName != null) {
-            parts[parts.length - 1] += ` --${s.edgeName}-->`;
-        }
-    }
-    return parts.join('\n  → ');
+    const overLimit = collapsed.length > maxSteps;
+    const shown = overLimit
+        ? [...collapsed.slice(0, 3), ...collapsed.slice(-2)]
+        : collapsed;
+    // Render as a top-down indented tree so the retention direction is
+    // unambiguous (GC root on top, each node retained by the one above it).
+    // `s.edgeName` is the OUTGOING edge (s -> next); the edge pointing INTO a node
+    // is the previous node's edgeName, which is what the renderer surfaces.
+    const treeSteps = shown.map((s, i) => ({
+        id: s.nodeId,
+        name: truncateNodeName(s.name, s.type, s.selfSize, 50),
+        type: s.type,
+        retainedSize: s.retainedSize,
+        // `shown[i - 1].edgeName` is the previous node's OUTGOING edge = the edge
+        // INTO this node, but only when the two are actually adjacent. At the
+        // truncation boundary (i === 3) `shown[2]`'s outgoing edge points into the
+        // elided `collapsed[3]`, not into this tail node, so leave it undefined
+        // rather than misattribute an unrelated edge — the gap is already marked by
+        // `collapsedBefore`.
+        edgeName: i > 0 && !(overLimit && i === 3) ? shown[i - 1].edgeName : undefined,
+        // The two tail nodes were sliced off the end, so the hop into the first of
+        // them crosses the elided middle — mark the gap.
+        collapsedBefore: overLimit && i === 3 ? collapsed.length - 5 : undefined,
+    }));
+    return formatRetainerTree(treeSteps, { showSizes: true });
 }
 function computeTraceOverlap(a, b) {
     let prefixLen = 0;
@@ -1265,7 +1274,7 @@ export function registerAutoInvestigate(server) {
                         lines.push(`**Retainer chain:** (same chain as #${traceMatch.matchedIndex + 1}) → [${divergeEdge}] ${divergeName} — ${formatBytes(f.node.retainedSize)}`);
                     }
                     else {
-                        lines.push(`**Retainer chain:** ${formatTrace(f.trace, 8)}`);
+                        lines.push(`**Retainer chain:**\n${formatTrace(f.trace, 8)}`);
                     }
                     lines.push('');
                     lines.push(`**Alternate retainers of the same subtree** (retained sizes overlap — not additive): @${f.node.id} (${formatBytes(f.node.retainedSize)})` +
@@ -1286,7 +1295,7 @@ export function registerAutoInvestigate(server) {
                 else {
                     lines.push(`### ${i + 1}. ${sevIcon} [${f.severity}] @${f.node.id} \`${name}\` (${f.node.type}) — ${formatBytes(f.node.retainedSize)}${pct}`);
                     lines.push('');
-                    lines.push(`**Retainer chain:** ${formatTrace(f.trace, 8)}`);
+                    lines.push(`**Retainer chain:**\n${formatTrace(f.trace, 8)}`);
                 }
                 previousTraces.push(f.trace);
                 const instrNote = instrumentationRetainerNote(f.trace);
@@ -1419,8 +1428,16 @@ export function registerAutoInvestigate(server) {
                     const sampleNodes = shapeBuckets.get(s.properties.join(',')) ?? [];
                     if (sampleNodes.length < 50)
                         continue;
-                    // Analyze each property's cardinality and value characteristics
+                    const sampleCount = sampleNodes.length;
+                    const shapeKey = s.properties.join(',');
+                    const propStats = [];
                     for (const propName of s.properties) {
+                        // Skip prototype / internal pseudo-properties — they are not data
+                        // columns, so "pre-filter / intern this column" advice is noise
+                        // (Feedback round 4 §2).
+                        if (propName === '__proto__' || propName.startsWith('<')) {
+                            continue;
+                        }
                         const values = new Set();
                         let totalValueSize = 0;
                         let stringValueCount = 0;
@@ -1445,39 +1462,64 @@ export function registerAutoInvestigate(server) {
                                 }
                             }
                         }
-                        const cardinality = values.size;
-                        const sampleCount = sampleNodes.length;
-                        const uniqueKey = looksUniqueKey(propName);
-                        const shapeKey = s.properties.join(',');
-                        // Same-object duplication vs genuine low cardinality (§1b): a field
-                        // that *should* be unique per record but has far fewer distinct
-                        // values than sampled instances means the SAME records are retained
-                        // N times — a retention/concurrency fix, not interning.
-                        if (uniqueKey &&
-                            sampleCount >= 100 &&
-                            cardinality >= 1 &&
-                            cardinality < sampleCount * 0.6 &&
-                            !dupShapesSeen.has(shapeKey)) {
-                            const dupFactor = Math.round(sampleCount / Math.max(1, cardinality));
-                            if (dupFactor >= 2) {
-                                dupShapesSeen.add(shapeKey);
-                                duplicationAlerts.push(`- \`${propName}\` (a unique-looking key) has only **${formatNumber(cardinality)} distinct value(s)** across ${formatNumber(sampleCount)} sampled of ${formatNumber(s.count)} total \`{${s.properties.slice(0, 4).join(', ')}${s.properties.length > 4 ? ', …' : ''}}\` instances — looks like **~${dupFactor} retained copies of the same records**, not a low-cardinality column. Investigate **retention/concurrency** (e.g. many concurrent requests each holding a full copy of this dataset), NOT string interning.`);
-                            }
+                        propStats.push({
+                            name: propName,
+                            cardinality: values.size,
+                            stringValueCount,
+                            totalValueSize,
+                            allUnique,
+                        });
+                    }
+                    // Same-object duplication (§1b), copy-factor corrected (round 4 §1a):
+                    // derive the factor from the MOST-DISTINCT string-valued field — the
+                    // record's true discriminator — NOT from an arbitrary unique-looking
+                    // field. The old code did `sampleCount / cardinality` on any
+                    // `*_id`-shaped key, so a CONSTANT field (e.g. `gala_project_id`
+                    // with 1 value) reported "~200 copies" when the real duplication was
+                    // 2×. If even the most-distinct field repeats, the whole record is
+                    // duplicated; if the most-distinct field is ~unique, there is no
+                    // duplication regardless of how many constant columns exist.
+                    const stringStats = propStats.filter(p => p.stringValueCount >= sampleCount * 0.5);
+                    let maxCard = 0;
+                    let discrim = '';
+                    for (const p of stringStats) {
+                        if (p.cardinality > maxCard) {
+                            maxCard = p.cardinality;
+                            discrim = p.name;
                         }
-                        else if (!uniqueKey &&
-                            cardinality <= 20 &&
-                            sampleCount >= 100) {
-                            // Genuine low-cardinality column.
-                            columnAlerts.push(`- Property \`${propName}\` has only **${cardinality} unique value(s)** across ${formatNumber(s.count)} instances — low-cardinality column suitable for pre-filtering at the data source or string interning`);
+                    }
+                    if (stringStats.length > 0 &&
+                        maxCard >= 1 &&
+                        maxCard < sampleCount * 0.6 &&
+                        sampleCount >= 100 &&
+                        !dupShapesSeen.has(shapeKey)) {
+                        const copyFactor = Math.round(sampleCount / maxCard);
+                        if (copyFactor >= 2) {
+                            dupShapesSeen.add(shapeKey);
+                            duplicationAlerts.push(`- \`{${s.properties.slice(0, 4).join(', ')}${s.properties.length > 4 ? ', …' : ''}}\` (${formatNumber(s.count)} total instances): even the most-distinct field \`${discrim}\` has only **${formatNumber(maxCard)} distinct value(s)** across ${formatNumber(sampleCount)} sampled — the same records appear to be retained **≈${copyFactor}×** (sample-based estimate; confirm the exact factor with \`memlab_property_distribution\` on \`${discrim}\`, or a content-hash count). Investigate **retention/concurrency** (e.g. many concurrent requests each holding a full copy of this dataset, or the same listing materialized twice), NOT string interning.`);
+                        }
+                    }
+                    // Pass 2: per-property low-cardinality + high-cost-unique notes.
+                    for (const p of propStats) {
+                        const uniqueKey = looksUniqueKey(p.name);
+                        if (!uniqueKey && p.cardinality <= 20 && sampleCount >= 100) {
+                            // Genuine low-cardinality column. Only suggest string interning
+                            // when the column actually holds strings — interning a numeric
+                            // (SMI/heap-number) or boolean column is meaningless
+                            // (Feedback round 4 §2).
+                            const isStringColumn = p.stringValueCount >= sampleCount * 0.5;
+                            columnAlerts.push(isStringColumn
+                                ? `- Property \`${p.name}\` has only **${p.cardinality} unique value(s)** across ${formatNumber(s.count)} instances — low-cardinality column suitable for pre-filtering at the data source or string interning`
+                                : `- Property \`${p.name}\` has only **${p.cardinality} unique value(s)** across ${formatNumber(s.count)} instances — low-cardinality column suitable for pre-filtering at the data source`);
                         }
-                        // High-cost unique: all values unique, string, large average size
-                        if (allUnique &&
-                            stringValueCount > sampleCount * 0.8 &&
-                            cardinality > sampleCount * 0.9) {
-                            const avgSize = totalValueSize / stringValueCount;
+                        // High-cost unique: all values unique, string, large average size.
+                        if (p.allUnique &&
+                            p.stringValueCount > sampleCount * 0.8 &&
+                            p.cardinality > sampleCount * 0.9) {
+                            const avgSize = p.totalValueSize / p.stringValueCount;
                             if (avgSize > 50 && s.count > 10_000) {
                                 const estimatedWaste = avgSize * s.count;
-                                columnAlerts.push(`- Property \`${propName}\` has **all unique string values** (avg ${Math.round(avgSize)}B each × ${formatNumber(s.count)} instances = ~${formatBytes(estimatedWaste)}) — verify this field is needed by consumers`);
+                                columnAlerts.push(`- Property \`${p.name}\` has **all unique string values** (avg ${Math.round(avgSize)}B each × ${formatNumber(s.count)} instances = ~${formatBytes(estimatedWaste)}) — verify this field is needed by consumers`);
                             }
                         }
                     }