@memlab/mcp-server 2.18.1 → 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/batch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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';
+export declare function registerBatch(server: McpServer): void;
+//# sourceMappingURL=batch.d.ts.map

package/dist/tools/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/tools/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA2CvE,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2JrD"}

package/dist/tools/batch.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 { getRegisteredTool, listToolNames } from '../tool-registry.js';
+import { errorResult, toolResult } from '../utils.js';
+/**
+ * A failed step usually does NOT throw. Tool handlers catch their own errors and
+ * return `errorResult`, which is a normal MCP envelope carrying `isError: true`,
+ * so treating only exceptions as failures silently mislabels those steps as
+ * successful — and, worse, makes `stop_on_error` a no-op for the most common
+ * failure there is.
+ */
+function isErrorResult(res) {
+    return (res != null &&
+        typeof res === 'object' &&
+        res.isError === true);
+}
+function renderToolText(res) {
+    // Tool handlers return the MCP content envelope produced by `toolResult`.
+    if (res && typeof res === 'object' && 'content' in res) {
+        const content = res.content;
+        if (Array.isArray(content)) {
+            return content
+                .map(c => c && typeof c === 'object' && 'text' in c
+                ? String(c.text ?? '')
+                : JSON.stringify(c))
+                .join('\n');
+        }
+    }
+    return typeof res === 'string' ? res : JSON.stringify(res);
+}
+export function registerBatch(server) {
+    server.tool('memlab_batch', 'Run several memlab tools against ONE snapshot load, in order, and return all their outputs together. ' +
+        'The natural unit of heap work is "load snapshot X, then run these N tools", but loading is by far the dominant cost — a 380 MB / 4M-node snapshot takes minutes to parse and build a dominator tree, and an MCP session that drops (or a client that cannot attach) makes every call pay it again. ' +
+        'Pass `load` to load a snapshot first (same arguments as memlab_load_snapshot); omit it to run against the already-resident snapshot. ' +
+        "Steps run sequentially and see each other's side effects, so a step may depend on an earlier one (e.g. load -> check_health -> retainer_summary). " +
+        "Every step's tool name AND arguments are validated before step 0 runs, so a step missing a required argument fails the batch immediately instead of after the snapshot load has been paid for. " +
+        'NOTE ON TIMEOUTS: the whole batch runs under a single wall-clock guardrail, not one per step — size it with `timeout_ms` (e.g. 600000 for a load plus several whole-heap scans).', {
+        load: z
+            .object({
+            file_path: z.string(),
+            alias: z.string().optional(),
+            keep_previous: z.boolean().optional(),
+            quiet: z.boolean().optional(),
+            max_file_size_mb: z.number().optional(),
+        })
+            .optional()
+            .describe('Optional memlab_load_snapshot arguments to run as step 0. Omit to use the resident snapshot.'),
+        steps: z
+            .array(z.object({
+            tool: z.string().describe('Tool name, e.g. "memlab_check_health".'),
+            args: z
+                .record(z.unknown())
+                .optional()
+                .describe('Arguments object for that tool (default {}).'),
+        }))
+            .min(1)
+            .describe('Ordered list of tools to run after the optional load.'),
+        stop_on_error: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Stop at the first failing step (default false: record the error and continue).'),
+    }, async ({ load, steps, stop_on_error }) => {
+        try {
+            const plan = [];
+            if (load != null) {
+                plan.push({
+                    tool: 'memlab_load_snapshot',
+                    args: load,
+                });
+            }
+            for (const s of steps) {
+                plan.push({
+                    tool: s.tool,
+                    args: (s.args ?? {}),
+                });
+            }
+            const unknown = plan
+                .map(p => p.tool)
+                .filter(name => getRegisteredTool(name) == null);
+            if (unknown.length > 0) {
+                return errorResult(new Error(`Unknown tool(s): ${[...new Set(unknown)].join(', ')}. Available: ${listToolNames().join(', ')}`));
+            }
+            // Validate EVERY step's arguments before running step 0.
+            //
+            // Parsing inside the execution loop means a step that is missing a
+            // required argument fails only after the load has been paid for — and
+            // the load is the expensive part: on a 243 MB snapshot this cost a full
+            // parse twice in one session (`weakmap_entries` and `retainer_layers`,
+            // both missing `node_id`) before the batch reported anything. The
+            // information needed to refuse was available before any work started.
+            const planned = [];
+            const argErrors = [];
+            plan.forEach(({ tool, args }, i) => {
+                const entry = getRegisteredTool(tool);
+                if (entry == null)
+                    return;
+                try {
+                    // Apply the tool's own zod shape so `.default()` values are
+                    // materialized exactly as they are for a direct MCP call. Without
+                    // this a step that omits an optional gets `undefined` and a scan
+                    // gated on e.g. `min_count` silently returns nothing.
+                    planned.push({
+                        tool,
+                        parsed: entry.shape != null
+                            ? z.object(entry.shape).parse(args)
+                            : args,
+                    });
+                }
+                catch (err) {
+                    const detail = err instanceof z.ZodError
+                        ? err.issues
+                            .map(iss => `${iss.path.join('.') || '(root)'}: ${iss.message}`)
+                            .join('; ')
+                        : err instanceof Error
+                            ? err.message
+                            : String(err);
+                    argErrors.push(`step ${i + 1} \`${tool}\` — ${detail}`);
+                }
+            });
+            if (argErrors.length > 0) {
+                return errorResult(new Error(`${argErrors.length} step(s) have invalid arguments; nothing was run (the snapshot load is the expensive part of a batch, so the whole plan is checked first):\n` +
+                    argErrors.map(e => `- ${e}`).join('\n')));
+            }
+            const results = [];
+            for (const { tool, parsed } of planned) {
+                const entry = getRegisteredTool(tool);
+                if (entry == null)
+                    continue;
+                try {
+                    const res = await entry.handler(parsed, {});
+                    const ok = !isErrorResult(res);
+                    results.push({ tool, ok, text: renderToolText(res) });
+                    if (!ok && stop_on_error)
+                        break;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    results.push({ tool, ok: false, text: `ERROR: ${msg}` });
+                    if (stop_on_error)
+                        break;
+                }
+            }
+            const failed = results.filter(r => !r.ok).length;
+            const header = `# Batch: ${results.length} step(s) run` +
+                (failed > 0 ? `, ${failed} failed` : '') +
+                (results.length < plan.length
+                    ? ` (stopped early; ${plan.length - results.length} not run)`
+                    : '');
+            const body = results
+                .map((r, i) => `\n---\n\n## Step ${i + 1}/${plan.length}: \`${r.tool}\`${r.ok ? '' : ' — FAILED'}\n\n${r.text}`)
+                .join('\n');
+            return toolResult(`${header}\n${body}`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=batch.js.map

package/dist/tools/batch.js.map

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

package/dist/tools/cache-analysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-analysis.d.ts","sourceRoot":"","sources":["../../src/tools/cache-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAqQvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAooB7D"}
+{"version":3,"file":"cache-analysis.d.ts","sourceRoot":"","sources":["../../src/tools/cache-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA8WvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAosB7D"}

package/dist/tools/cache-analysis.js

@@ -11,13 +11,81 @@ import { z } from 'zod';
 import { getSnapshot, getSnapshotMetadata } from '../heap-state.js';
 import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, suggestionsSuppressed, } from '../utils.js';
 const CACHE_EDGE_RE = /cache|memo|store|registry|lru|dedup|pool|index|lookup|byId|byKey/i;
+/**
+ * Sibling property names specific enough to mark a ring buffer on their own: a
+ * plain cache has no reason to track where the next slot to overwrite is.
+ */
+const RING_WRITE_CURSOR_PROPS = new Set([
+    'localCursor',
+    'writeFrom',
+    'writeIndex',
+    'writeCursor',
+    'writePos',
+    'nextSlot',
+]);
+/**
+ * Cursor-ish names that are also carried by linked lists, queues, iterators,
+ * tree-traversal state and cursor-paginated result sets. Alone they are not
+ * evidence of a ring — a genuine unbounded cache whose owner happens to expose
+ * `head` would be dropped as bounded — so they only count when paired with a
+ * capacity control.
+ */
+const RING_AMBIGUOUS_CURSOR_PROPS = new Set([
+    'cursor',
+    'head',
+    'tail',
+    'nextIndex',
+    'readIndex',
+    'readCursor',
+]);
+/**
+ * Anchored on purpose: an unanchored pattern matches any name merely
+ * *containing* the token, so predicates and unrelated config (`hasCapacity`,
+ * `overCapacity`, `defaultMaxSize`) would read as capacity controls.
+ */
+const RING_CAPACITY_PROP_RE = /^_?(?:capacity|log_?capacity|max_?size|buffer_?size|ring_?size)$/i;
+/**
+ * A fixed-capacity ring buffer looks exactly like an unbounded cache to a
+ * size-based heuristic: a large backing array full of entries, strongly held,
+ * with no eviction call in sight. It is the opposite — it can never grow.
+ *
+ * Observed false positive: a logger's 150,000-slot ring was reported as
+ * "cache-like, missing eviction is a likely leak" because the tool counted the
+ * ~11k non-null slots. Detect the shape from the owner's sibling properties (a
+ * write cursor and/or a capacity control) so it is labelled bounded instead.
+ *
+ * Biased towards under-detection: a missed ring is a false leak candidate the
+ * caller can dismiss, while a wrongly-detected one drops a real leak silently.
+ */
+function looksLikeRingBuffer(owner) {
+    if (!owner)
+        return false;
+    let hasAmbiguousCursor = false;
+    let hasCapacity = false;
+    for (const edge of owner.references) {
+        const name = String(edge.name_or_index);
+        if (RING_WRITE_CURSOR_PROPS.has(name))
+            return true;
+        if (RING_AMBIGUOUS_CURSOR_PROPS.has(name))
+            hasAmbiguousCursor = true;
+        if (RING_CAPACITY_PROP_RE.test(name))
+            hasCapacity = true;
+        if (hasAmbiguousCursor && hasCapacity)
+            return true;
+    }
+    return false;
+}
 /**
  * Distinguish a genuine cache (named like one, owned by a cache class, or
  * carrying cache config) from a plain large collection / per-request working
  * set. Avoids over-labeling every big Map/Array as an "unbounded cache"
  * (Feedback §2c).
  */
-function classifyCollection(collectionType, ownerEdge, framework) {
+function classifyCollection(collectionType, ownerEdge, framework, owner) {
+    // Checked first: a bounded structure is not a leak candidate however it is
+    // named, and ring buffers are frequently named like caches/logs.
+    if (looksLikeRingBuffer(owner ?? null))
+        return 'ring-buffer';
     if (framework)
         return 'cache-like';
     if (/cache/i.test(collectionType))
@@ -77,6 +145,7 @@ function getOwnerInfo(node) {
         return {
             name: truncateNodeName(from.name, from.type, from.self_size, 40),
             edge: edgeName,
+            node: from,
         };
     }
     if (from.hasPathEdge) {
@@ -87,11 +156,40 @@ function getOwnerInfo(node) {
                 return {
                     name: truncateNodeName(outer.name, outer.type, outer.self_size, 40),
                     edge: `${String(outerEdge.name_or_index)}.${edgeName}`,
+                    node: outer,
                 };
             }
         }
     }
-    return { name: from.name, edge: edgeName };
+    return { name: from.name, edge: edgeName, node: from };
+}
+/**
+ * O(1)-ish upper bound on a collection's entry count, used to decide whether a
+ * collection is worth counting properly.
+ *
+ * Why it exists: `cache_analysis` gated every collection on `min_retained_size`
+ * first, so a collection that is LONG but cheap — many entries of small or
+ * shared values — was invisible. A positive-control Map planted for a leak hunt
+ * sat under the 512 KB default and never appeared, which is the one case the
+ * tool most needs to catch. Length and bytes are different questions.
+ *
+ * The full `countEntries` walk is O(entries), so running it on every Map/Set/
+ * Array in a multi-million-node heap is not affordable. Reading the backing
+ * table's `edge_count` is a single lookup and bounds the expensive walk to
+ * collections that are plausibly long.
+ */
+function approxEntryCount(node) {
+    if (node.name === 'Map' || node.name === 'Set') {
+        for (const edge of node.references) {
+            const eName = String(edge.name_or_index);
+            if ((eName === 'table' || eName === 'backing_store') &&
+                (edge.toNode.type === 'array' || edge.toNode.type === 'hidden')) {
+                const slots = edge.toNode.edge_count;
+                return node.name === 'Map' ? Math.floor(slots / 2) : slots;
+            }
+        }
+    }
+    return node.edge_count;
 }
 function countEntries(node) {
     if (node.name === 'Map' || node.name === 'Set') {
@@ -283,6 +381,8 @@ export function registerCacheAnalysis(server) {
             const totalSize = meta?.totalSize ?? 0;
             const typeSet = new Set(collection_types);
             const caches = [];
+            // Collections that clear `min_entries` but not `min_retained_size`.
+            const longButSmall = [];
             snapshot.nodes.forEach(node => {
                 if (node.id <= 3)
                     return;
@@ -290,11 +390,26 @@ export function registerCacheAnalysis(server) {
                     return;
                 if (node.type !== 'object')
                     return;
-                if (node.retainedSize < min_retained_size)
+                // Size-independent path: a collection that is long enough to matter is
+                // examined even when it is small in bytes (see approxEntryCount).
+                const bigEnough = node.retainedSize >= min_retained_size;
+                if (!bigEnough && approxEntryCount(node) < min_entries)
                     return;
                 const { entries: entryCount, tableSlots } = countEntries(node);
                 if (entryCount < min_entries)
                     return;
+                if (!bigEnough) {
+                    // Long but cheap. Reported in its own section rather than mixed into
+                    // the ranked table, whose ordering and thresholds callers rely on.
+                    longButSmall.push({
+                        nodeId: node.id,
+                        collectionType: node.name,
+                        entryCount,
+                        retainedSize: node.retainedSize,
+                        ownerName: getOwnerInfo(node).name,
+                    });
+                    return;
+                }
                 const owner = getOwnerInfo(node);
                 const framework = identifyCacheFramework(node, owner.edge);
                 const entry = {
@@ -308,7 +423,7 @@ export function registerCacheAnalysis(server) {
                     ownerEdge: owner.edge,
                     hasWeakRefs: hasWeakRefEntries(node),
                     framework,
-                    classification: classifyCollection(node.name, owner.edge, framework),
+                    classification: classifyCollection(node.name, owner.edge, framework, owner.node),
                 };
                 let inserted = false;
                 for (let i = 0; i < caches.length; i++) {
@@ -485,8 +600,42 @@ export function registerCacheAnalysis(server) {
                     }
                 });
             }
+            // Long-but-cheap collections. Rendered as its own section so the size
+            // threshold can no longer hide a growing collection outright — the
+            // failure that made a planted positive-control Map invisible.
+            const longButSmallSection = () => {
+                if (longButSmall.length === 0)
+                    return [];
+                longButSmall.sort((a, b) => b.entryCount - a.entryCount);
+                const top = longButSmall.slice(0, 10);
+                return [
+                    '',
+                    `### Long but small — ${formatNumber(longButSmall.length)} collection(s) with >= ${formatNumber(min_entries)} entries but under ${formatBytes(min_retained_size)} retained`,
+                    '',
+                    'These are excluded from the ranked table above by `min_retained_size`, but entry COUNT is the signal for unbounded growth — a collection that grows without bound is a leak whether or not its entries are large. Track these across a ladder.',
+                    '',
+                    markdownTable(['Collection', 'Entries', 'Retained', 'Owner', 'ID'], top.map(c => [
+                        c.collectionType,
+                        formatNumber(c.entryCount),
+                        formatBytes(c.retainedSize),
+                        c.ownerName.length > 40
+                            ? c.ownerName.slice(0, 37) + '…'
+                            : c.ownerName,
+                        `@${c.nodeId}`,
+                    ]), new Set([1, 2])),
+                    ...(longButSmall.length > top.length
+                        ? [
+                            '',
+                            `_… +${formatNumber(longButSmall.length - top.length)} more. Lower \`min_retained_size\` to rank them with the rest._`,
+                        ]
+                        : []),
+                ];
+            };
             if (caches.length === 0) {
-                return toolResult(`No unbounded caches found with >= ${min_entries} entries and >= ${formatBytes(min_retained_size)} retained. Try lowering the thresholds.`);
+                return toolResult([
+                    `No unbounded caches found with >= ${min_entries} entries and >= ${formatBytes(min_retained_size)} retained. Try lowering the thresholds.`,
+                    ...longButSmallSection(),
+                ].join('\n'));
             }
             const hasAnyFramework = caches.some(c => c.framework !== '');
             const hasSlotDifference = caches.some(c => c.tableSlots !== c.entryCount);
@@ -534,6 +683,7 @@ export function registerCacheAnalysis(server) {
                 '**Kind:**',
                 '- **cache-like** — named like a cache, owned by a cache class, or carrying TTL/maxSize config. Missing eviction here is a likely leak.',
                 '- **collection** — a plain large Map/Set/Array or per-request working set. Large is not the same as leaking; confirm it is actually retained across requests before treating it as a leak.',
+                '- **ring-buffer** — fixed-capacity buffer (the owner carries a write cursor and/or a capacity control). It looks like an unbounded cache to a size heuristic but cannot grow: **not a leak candidate**. Check the declared capacity before spending time on it.',
                 '',
                 '**Risk indicators:**',
                 '- **Weak? = No** means entries are strongly held and will never be evicted by GC',
@@ -748,6 +898,7 @@ export function registerCacheAnalysis(server) {
                     lines.push('', '_Entries have matching array lengths, child counts, and retained sizes. The cache key may not affect the cached data — consider deduplicating._');
                 }
             }
+            lines.push(...longButSmallSection());
             return toolResult(lines.join('\n'));
         }
         catch (err) {