@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/explain-delta.js

@@ -0,0 +1,221 @@
+/**
+ * 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 { getSnapshotByHandle, getMetadataByHandle, getCurrentHandle, listSnapshots, findResidentByPath, } from '../heap-state.js';
+import { getRegisteredTool } from '../tool-registry.js';
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+import { classifyArtifact } from '../artifact-classes.js';
+import { normalizeClassName } from './sequence-analysis.js';
+/**
+ * Attribute every node's SELF size to its immediate dominator's class.
+ *
+ * Self size, not retained: retained sizes overlap wherever objects nest, so
+ * summing them per owner reports more memory than exists (a sum over one class
+ * in a 200 MB heap has been measured at 5.9 GB). Self sizes partition the heap
+ * exactly, which is what makes two snapshots comparable.
+ *
+ * Immediate dominator, not nearest app-owned ancestor: resolving an owner chain
+ * per node needs a memo table the size of the heap, and on a multi-million-node
+ * snapshot that is a large allocation to make while answering a question about
+ * memory. The immediate dominator is already the accountable parent for the
+ * bytes hanging off it, and it is one field read per node.
+ */
+function attributeByOwner(snapshot) {
+    const byOwner = new Map();
+    let totalSelf = 0;
+    snapshot.nodes.forEach(node => {
+        if (node.id <= 3)
+            return;
+        totalSelf += node.self_size;
+        const dom = node.dominatorNode;
+        // Normalize the per-instance node id V8 appends to Context/scope names
+        // ("system / Context / scope @706909"). Those ids differ per capture, so
+        // without this every scope looks like an owner that appeared from nothing
+        // in the target and vanished from the baseline — pure phantom delta.
+        const key = dom == null || dom.id === node.id
+            ? '(GC roots)'
+            : dom.name.length > 0
+                ? normalizeClassName(dom.name)
+                : `(unnamed ${dom.type})`;
+        const e = byOwner.get(key);
+        if (e) {
+            e.selfBytes += node.self_size;
+            e.nodes++;
+        }
+        else {
+            byOwner.set(key, { selfBytes: node.self_size, nodes: 1 });
+        }
+    });
+    return { byOwner, totalSelf };
+}
+/**
+ * Resolve a `baseline` that turned out to be a file path by loading it into the
+ * session (keeping whatever is already resident), and return its handle.
+ *
+ * Dispatches to the registered `memlab_load_snapshot` handler rather than
+ * duplicating its guards — the ceilings, the memory-headroom check and the
+ * already-resident fast path all still apply.
+ */
+async function loadSnapshotByPath(filePath) {
+    const already = findResidentByPath(filePath);
+    if (already != null)
+        return already.handle;
+    const entry = getRegisteredTool('memlab_load_snapshot');
+    if (entry == null)
+        return null;
+    try {
+        const args = entry.shape != null
+            ? z
+                .object(entry.shape)
+                .parse({ file_path: filePath, keep_previous: true })
+            : { file_path: filePath, keep_previous: true };
+        await entry.handler(args, {});
+    }
+    catch {
+        return null;
+    }
+    return findResidentByPath(filePath)?.handle ?? null;
+}
+export function registerExplainDelta(server) {
+    server.tool('memlab_explain_delta', 'Explain WHERE a heap grew between two loaded snapshots, attributed by dominator (who owns the new bytes) rather than by class (what the new bytes are). ' +
+        '"Object grew by 99,418 instances" does not tell you what to fix; "the bytes hanging off CometStyleXSheet grew by 12 MB" does. Every node\'s SELF size is attributed to its immediate dominator\'s class and the two attributions are differenced, so the numbers partition the heap and add up — unlike a per-class sum of retained sizes, which double-counts nested objects and can exceed the heap. ' +
+        'Known measurement-artifact owners (JIT warmup, CDP inspector, a11y caches, captured Error stacks) are flagged so an inspector-driven delta is not read as an application regression. Both snapshots must be resident: load them with keep_previous:true.', {
+        baseline_handle: z
+            .string()
+            .optional()
+            .describe('Handle of the earlier snapshot (memlab_snapshots lists them). Its siblings memlab_artifact_budget and memlab_census_diff take a `baseline` PATH instead, so `baseline` is accepted here as an alias — a batch authored against the recipe used to fail argument validation on this one parameter alone.'),
+        baseline: z
+            .string()
+            .optional()
+            .describe('Alias for `baseline_handle`. Accepts a resident handle, or a file path — which is auto-loaded with keep_previous so the whole batch does not have to be re-authored.'),
+        target_handle: z
+            .string()
+            .optional()
+            .describe('Handle of the later snapshot. Defaults to the current snapshot.'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum owners to report per direction (default 20).'),
+        min_delta_bytes: z
+            .number()
+            .optional()
+            .default(65536)
+            .describe('Ignore owners whose attributed size moved by less than this (default 64 KB).'),
+        include_artifacts: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include owners that are known measurement artifacts (default false: counted in a one-line summary instead).'),
+    }, async ({ baseline_handle, baseline: baselineAlias, target_handle, limit, min_delta_bytes, include_artifacts, }) => {
+        try {
+            let baselineRef = baseline_handle ?? baselineAlias;
+            if (baselineRef == null) {
+                return errorResult('Pass `baseline_handle` (a resident snapshot handle) or `baseline` (a handle or a file path).');
+            }
+            // A path where a handle was expected is the documented sibling spelling,
+            // not a mistake: `artifact_budget` and `census_diff` both take paths.
+            // Loading it is exactly what the "must be resident" error tells the
+            // caller to go and do by hand, and a re-authored batch costs a reload of
+            // every rung.
+            if (getSnapshotByHandle(baselineRef) == null &&
+                /[/\\.]/.test(baselineRef)) {
+                const loaded = await loadSnapshotByPath(baselineRef);
+                if (loaded == null) {
+                    return errorResult(`\`baseline\` "${baselineRef}" is neither a resident handle nor a readable snapshot file.`);
+                }
+                baselineRef = loaded;
+            }
+            const targetHandle = target_handle ?? getCurrentHandle();
+            if (targetHandle == null) {
+                return errorResult('No current snapshot; pass target_handle.');
+            }
+            if (targetHandle === baselineRef) {
+                return errorResult('baseline_handle and target_handle are the same snapshot.');
+            }
+            const baselineSnapshot = getSnapshotByHandle(baselineRef);
+            const target = getSnapshotByHandle(targetHandle);
+            if (baselineSnapshot == null || target == null) {
+                const available = listSnapshots()
+                    .map(m => m.handle)
+                    .join(', ');
+                return errorResult(`Both snapshots must be resident. Missing: ${baselineSnapshot == null ? baselineRef : targetHandle}. Resident: ${available || '(none)'}. Load with memlab_load_snapshot({file_path, keep_previous: true}).`);
+            }
+            for (const h of [baselineRef, targetHandle]) {
+                if (getMetadataByHandle(h)?.light) {
+                    return errorResult(`Snapshot "${h}" was loaded in LIGHT mode and has no dominator tree, which this attribution requires. Reload it without light.`);
+                }
+            }
+            const a = attributeByOwner(baselineSnapshot);
+            const b = attributeByOwner(target);
+            const rows = [];
+            const owners = new Set([...a.byOwner.keys(), ...b.byOwner.keys()]);
+            for (const owner of owners) {
+                const before = a.byOwner.get(owner);
+                const after = b.byOwner.get(owner);
+                const delta = (after?.selfBytes ?? 0) - (before?.selfBytes ?? 0);
+                if (Math.abs(delta) < min_delta_bytes)
+                    continue;
+                rows.push({
+                    owner,
+                    delta,
+                    before: before?.selfBytes ?? 0,
+                    after: after?.selfBytes ?? 0,
+                    nodesDelta: (after?.nodes ?? 0) - (before?.nodes ?? 0),
+                    artifact: classifyArtifact(owner) != null,
+                });
+            }
+            const totalDelta = b.totalSelf - a.totalSelf;
+            const lines = [
+                `## Heap delta by owner: "${baselineRef}" → "${targetHandle}"`,
+                '',
+                `Total self size ${totalDelta >= 0 ? 'grew' : 'shrank'} by **${formatBytes(Math.abs(totalDelta))}** (${formatBytes(a.totalSelf)} → ${formatBytes(b.totalSelf)}).`,
+                '',
+            ];
+            const artifactRows = rows.filter(r => r.artifact);
+            const usable = include_artifacts ? rows : rows.filter(r => !r.artifact);
+            const grew = usable
+                .filter(r => r.delta > 0)
+                .sort((x, y) => y.delta - x.delta)
+                .slice(0, limit);
+            const shrank = usable
+                .filter(r => r.delta < 0)
+                .sort((x, y) => x.delta - y.delta)
+                .slice(0, limit);
+            if (grew.length === 0 && shrank.length === 0) {
+                lines.push(`No owner moved by at least ${formatBytes(min_delta_bytes)}. The change is spread thinly rather than concentrated under one owner — lower \`min_delta_bytes\`, or compare class counts with \`memlab_diff_snapshots\`.`);
+                return toolResult(lines.join('\n'));
+            }
+            const render = (rs) => markdownTable(['Owner (dominator class)', 'Δ self', 'Before', 'After', 'Δ nodes'], rs.map(r => [
+                r.owner.length > 44 ? r.owner.slice(0, 41) + '…' : r.owner,
+                `${r.delta >= 0 ? '+' : '−'}${formatBytes(Math.abs(r.delta))}`,
+                formatBytes(r.before),
+                formatBytes(r.after),
+                `${r.nodesDelta >= 0 ? '+' : '−'}${formatNumber(Math.abs(r.nodesDelta))}`,
+            ]), new Set([1, 2, 3, 4]));
+            if (grew.length > 0) {
+                lines.push('### Owners that grew', '', render(grew), '');
+            }
+            if (shrank.length > 0) {
+                lines.push('### Owners that shrank', '', render(shrank), '');
+            }
+            if (!include_artifacts && artifactRows.length > 0) {
+                const bytes = artifactRows.reduce((s, r) => s + r.delta, 0);
+                lines.push(`> 🧹 **${formatNumber(artifactRows.length)} owner(s) suppressed as known measurement artifacts** (net ${bytes >= 0 ? '+' : '−'}${formatBytes(Math.abs(bytes))}) — JIT warmup, CDP inspector retention, a11y caches, captured Error stacks. Pass \`include_artifacts: true\` to see them.`, '> Note the split of responsibilities: the JIT-warmup families counted here (`system/Code`, `InstructionStream`, `BytecodeArray`, `ProtectedFixedArray`) are NOT counted by `memlab_dev_artifacts`, which measures retention by a dev root instead. Neither total is the whole artifact bill on its own — read both before deciding how much of a round is real.', '');
+            }
+            lines.push('_Attribution is by IMMEDIATE dominator and uses SELF size, so the rows partition the heap and sum to the total above. An owner growing does not prove a leak — a cache filling legitimately looks identical here; use `memlab_dominator_chain` on an instance to find the accountable application object, and a ladder (`memlab_leak_report`) to tell filling from unbounded growth._');
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=explain-delta.js.map

package/dist/tools/explain-delta.js.map

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

package/dist/tools/find-nodes-by-class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-nodes-by-class.d.ts","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAgBvE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwFhE"}
+{"version":3,"file":"find-nodes-by-class.d.ts","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAiBvE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2MhE"}

package/dist/tools/find-nodes-by-class.js

@@ -11,26 +11,94 @@ import memlabCore from '@memlab/core';
 const { utils, NumericSet } = memlabCore;
 import { z } from 'zod';
 import { getSnapshot } from '../heap-state.js';
-import { filterLargestObjects, serializeNodeSummary, formatNodeSummaryTable, formatNumber, formatBytes, errorResult, toolResult, } from '../utils.js';
+import { filterLargestObjects, serializeNodeSummary, formatNodeSummaryTable, formatNumber, formatBytes, errorResult, toolResult, makeNamePatternTest, } from '../utils.js';
 export function registerFindNodesByClass(server) {
-    server.tool('memlab_find_nodes_by_class', 'Find heap objects by constructor/class name. Returns matching objects sorted by retained size. Follow up with memlab_retainer_trace on a result node to see why it is retained, memlab_get_references to inspect its properties, or memlab_retainer_summary to find common retainer patterns across all instances.', {
+    server.tool('memlab_find_nodes_by_class', 'Find heap nodes by constructor/class name, exactly (class_name) or by case-insensitive regex/substring (name_pattern). Matches ANY node type by default (object, closure, array, string, native, …) — pass node_type to narrow. Ordering is controlled by order: the biggest by retained size (default), or the newest by node id. If the exact name matches nothing, reports near-miss names and the types they exist under instead of a bare "not found". Follow up with memlab_retainer_trace on a result node to see why it is retained, memlab_get_references to inspect its properties, or memlab_retainer_summary to find common retainer patterns across all instances.', {
         class_name: z
             .string()
-            .describe('The constructor or class name to search for'),
+            .optional()
+            .describe('The exact constructor or class name to search for. Either this or name_pattern is required.'),
+        name_pattern: z
+            .string()
+            .optional()
+            .describe('Match class names by pattern instead of exactly — a case-insensitive regular expression, or a plain substring when the pattern is not valid regex (e.g. "blink::UndoStep", "^WAWeb", "Collection$"). Use when the exact name is unknown, or to sweep a family in one call. Combined with class_name, both must match.'),
+        order: z
+            .enum(['retained_size', 'newest'])
+            .optional()
+            .default('retained_size')
+            .describe('How to pick which instances to show. "retained_size" (default) shows the biggest. "newest" shows the highest node ids — V8 assigns ids in allocation order, so within one snapshot this approximates the most recently allocated instances. When a class has grown from N to 10N across a ladder, the accumulating tail is what you want to inspect, and the biggest instances are usually the oldest — not the ones that are piling up. Approximate: ids are an allocation-order proxy, not a timestamp.'),
+        node_type: z
+            .string()
+            .optional()
+            .describe('Restrict to a single heap node type (e.g. "object", "closure", "array", "string", "native"). Omit to match every type — which is the default because class names surfaced by other tools (memlab_sequence_analysis reports "type::name") are frequently closures or arrays, not objects.'),
         output_mode: z
             .enum(['full', 'count', 'ids'])
             .optional()
             .default('full')
-            .describe('Output verbosity: "full" returns node summaries sorted by retained size (default), "count" returns only total count and aggregate retained size, "ids" returns only node IDs sorted by retained size'),
+            .describe('Output verbosity: "full" returns node summaries (default), "count" returns only total count and aggregate retained size, "ids" returns only node IDs. "full" and "ids" are both ordered by the "order" parameter, not always by retained size.'),
         limit: z
             .number()
+            .int()
+            .min(1)
             .optional()
             .default(20)
             .describe('Maximum number of results (default 20)'),
-    }, async ({ class_name, output_mode, limit }) => {
+    }, async ({ class_name, name_pattern, node_type, output_mode, limit, order, }) => {
         try {
+            if (class_name == null && name_pattern == null) {
+                return errorResult('Pass class_name (exact) or name_pattern (regex/substring); one of the two is required.');
+            }
             const snapshot = getSnapshot();
-            const classFilter = (node) => node.name === class_name && node.type === 'object';
+            const nameMatches = makeNamePatternTest(name_pattern);
+            const label = class_name ?? `/${name_pattern}/`;
+            // Historically this hard-filtered `type === 'object'`, so closures,
+            // arrays, strings and natives were invisible: a class reported as a top
+            // grower by memlab_sequence_analysis (which groups by `type::name`)
+            // could return "No objects found" here, e.g. the closure `setValues_$0`.
+            // Default to every type and let the caller narrow explicitly.
+            const classFilter = (node) => (class_name == null || node.name === class_name) &&
+                nameMatches(node.name) &&
+                (node_type == null || node.type === node_type);
+            // Zero exact matches is usually a type filter or a near-miss name, not
+            // an empty heap — say which, so the caller does not conclude the class
+            // is absent.
+            const notFound = () => {
+                // The near-miss report keys on an exact name; with only a pattern
+                // there is no "similar name" to suggest — say what was searched
+                // instead of pretending to have a suggestion.
+                if (class_name == null) {
+                    return `No nodes whose class name matches ${label}${node_type ? ` with node_type="${node_type}"` : ''}. The pattern is a case-insensitive regex (falling back to substring) — widen it, or drop node_type.`;
+                }
+                const byType = new Map();
+                const similar = new Map();
+                const needle = class_name.toLowerCase();
+                snapshot.nodes.forEach(node => {
+                    if (node.name === class_name) {
+                        byType.set(node.type, (byType.get(node.type) ?? 0) + 1);
+                    }
+                    else if (node.name.length < 120 &&
+                        node.name.toLowerCase().includes(needle)) {
+                        const k = `${node.name} (${node.type})`;
+                        similar.set(k, (similar.get(k) ?? 0) + 1);
+                    }
+                });
+                if (byType.size > 0) {
+                    const got = [...byType.entries()]
+                        .sort((a, b) => b[1] - a[1])
+                        .map(([t, n]) => `${t} (${formatNumber(n)})`)
+                        .join(', ');
+                    return `No nodes named "${class_name}" with node_type="${node_type ?? 'any'}". It DOES exist under: ${got}. Re-run without node_type, or with the matching one.`;
+                }
+                if (similar.size > 0) {
+                    const top = [...similar.entries()]
+                        .sort((a, b) => b[1] - a[1])
+                        .slice(0, 8)
+                        .map(([k, n]) => `${k} ×${formatNumber(n)}`)
+                        .join(', ');
+                    return `No nodes named exactly "${class_name}". Similar names present: ${top}`;
+                }
+                return `No nodes found with class "${class_name}" (no similar names either — check the snapshot is the one you expect).`;
+            };
             if (output_mode === 'count') {
                 let totalCount = 0;
                 let totalSelf = 0;
@@ -43,15 +111,46 @@ export function registerFindNodesByClass(server) {
                     nodeIds.add(node.id);
                 });
                 if (totalCount === 0) {
-                    return toolResult(`No objects found with class "${class_name}"`);
+                    return toolResult(notFound());
                 }
                 // Dominator-aware aggregate: instances of a class often nest on the
                 // dominator tree (e.g. a Foo retaining another Foo), so a raw sum of
                 // retainedSize would double-count and can exceed 100% of heap.
                 const totalRetained = utils.aggregateDominatorMetrics(nodeIds, snapshot, () => true, (node) => node.retainedSize);
-                return toolResult(`"${class_name}": ${formatNumber(totalCount)} instances, ${formatBytes(totalSelf)} total self size, ${formatBytes(totalRetained)} aggregate retained size (dominator-deduplicated)`);
+                return toolResult(`"${label}": ${formatNumber(totalCount)} instances, ${formatBytes(totalSelf)} total self size, ${formatBytes(totalRetained)} aggregate retained size (dominator-deduplicated)`);
+            }
+            let nodes;
+            if (order === 'newest') {
+                // Highest node ids = latest allocated within this snapshot. Keep a
+                // bounded top-N rather than collecting every match and sorting, so a
+                // class with a million instances does not materialize a huge array.
+                // Relies on the schema's integer `limit >= 1`: a fractional limit
+                // never satisfies `length === limit`, and `limit <= 0` would fall
+                // through to the eviction branch and keep one node anyway.
+                const newest = [];
+                let minKept = -1;
+                snapshot.nodes.forEach(node => {
+                    if (!classFilter(node))
+                        return;
+                    if (newest.length < limit) {
+                        newest.push(node);
+                        if (newest.length === limit) {
+                            newest.sort((a, b) => a.id - b.id);
+                            minKept = newest[0].id;
+                        }
+                        return;
+                    }
+                    if (node.id <= minKept)
+                        return;
+                    newest[0] = node;
+                    newest.sort((a, b) => a.id - b.id);
+                    minKept = newest[0].id;
+                });
+                nodes = newest.sort((a, b) => b.id - a.id);
+            }
+            else {
+                nodes = filterLargestObjects(snapshot, classFilter, limit);
             }
-            const nodes = filterLargestObjects(snapshot, classFilter, limit);
             let totalCount = 0;
             if (nodes.length === limit) {
                 snapshot.nodes.forEach(node => {
@@ -63,16 +162,16 @@ export function registerFindNodesByClass(server) {
                 totalCount = nodes.length;
             }
             if (nodes.length === 0) {
-                return toolResult(`No objects found with class "${class_name}"`);
+                return toolResult(notFound());
             }
             if (output_mode === 'ids') {
-                return toolResult(`"${class_name}": ${formatNumber(totalCount)} total instances (showing ${nodes.length} IDs by retained size)\n\nIDs: ${nodes.map(n => n.id).join(', ')}`);
+                return toolResult(`"${label}": ${formatNumber(totalCount)} total instances (showing ${nodes.length} IDs by ${order === 'newest' ? 'node id — newest first' : 'retained size'})\n\nIDs: ${nodes.map(n => n.id).join(', ')}`);
             }
             const summaries = nodes.map(serializeNodeSummary);
             const countNote = totalCount > nodes.length
-                ? ` (${formatNumber(totalCount)} total, showing top ${nodes.length})`
+                ? ` (${formatNumber(totalCount)} total, showing ${order === 'newest' ? `the ${nodes.length} newest by node id` : `top ${nodes.length} by retained size`})`
                 : '';
-            return toolResult(`Found ${formatNumber(totalCount)} "${class_name}" objects${countNote}\n\n${formatNodeSummaryTable(summaries)}`);
+            return toolResult(`Found ${formatNumber(totalCount)} "${label}" objects${countNote}\n\n${formatNodeSummaryTable(summaries)}`);
         }
         catch (err) {
             return errorResult(err);

package/dist/tools/find-nodes-by-class.js.map

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

package/dist/tools/finding-index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * 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 { z } from 'zod';
+/**
+ * A cross-round index of leak findings, keyed by a normalized retainer-path
+ * signature.
+ *
+ * The problem this solves is the most expensive one a hunt hits: rounds
+ * re-discover leaks that are already known or already fixed. One measured round
+ * produced three findings — a listener accumulation, a completion-map grower and
+ * a module-registry grower — all three of which were known, two already fixed
+ * behind gates, and the first only visible because the gated fixes were not
+ * enabled. That is an entire round spent re-deriving history.
+ *
+ * Why a retainer-path signature rather than the class name: the class that grows
+ * is rarely distinctive (`Object`, `Array`, `(object properties)` are the top
+ * growers in almost every heap), while the PATH that retains it is. Node ids,
+ * array indices and per-instance scope ids differ per capture, so they are
+ * stripped; what remains — the ordered edge names and class names — is stable
+ * across captures of the same leak and different between different leaks.
+ *
+ * Deliberately local (a JSON file), not a service: the index is only useful if
+ * it is written by default on every round, and anything requiring a backend
+ * would not be. It is seeded from prior runs' manifests.
+ */
+/**
+ * Where the index lives, most specific wins.
+ *
+ * The default is a per-machine home directory, and that default is the reason
+ * the tool has already produced a wrong verdict: an index with no history
+ * answers `check` with **NEW** for a finding that is fully documented and
+ * already has a fix diff. A home-dir file cannot be shared, does not survive a
+ * host change, and is empty on every new devserver — so the failure recurs for
+ * every operator rather than once.
+ *
+ * `MEMLAB_FINDINGS_INDEX` therefore points at a checked-in, shared file, and
+ * `workstream` scopes several of them side by side. The home-dir path is kept as
+ * the fallback so nothing that already works breaks.
+ */
+export declare function resolveIndexPath(workstream?: string): string;
+interface Finding {
+    fingerprint: string;
+    signature: string;
+    growing_classes: string[];
+    first_seen_round: string;
+    last_seen_round: string;
+    status: 'new' | 'known' | 'fixed';
+    fixed_behind?: string;
+    note?: string;
+    seen_count: number;
+}
+interface FindingIndex {
+    version: number;
+    findings: Record<string, Finding>;
+    combos_driven: Record<string, string[]>;
+}
+/**
+ * Findings accepted by `action: "import"`.
+ *
+ * Loose on purpose: the source is a hand-maintained team document or a previous
+ * round's notes, and rejecting a row for a missing optional field would mean the
+ * bootstrap does not happen at all — which is the status quo this fixes.
+ */
+declare const IMPORTED_FINDING_SCHEMA: z.ZodObject<{
+    retainer_path: z.ZodOptional<z.ZodString>;
+    signature: z.ZodOptional<z.ZodString>;
+    growing_classes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    round: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["new", "known", "fixed"]>>;
+    fixed_behind: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status?: "fixed" | "new" | "known" | undefined;
+    note?: string | undefined;
+    retainer_path?: string | undefined;
+    signature?: string | undefined;
+    growing_classes?: string[] | undefined;
+    round?: string | undefined;
+    fixed_behind?: string | undefined;
+}, {
+    status?: "fixed" | "new" | "known" | undefined;
+    note?: string | undefined;
+    retainer_path?: string | undefined;
+    signature?: string | undefined;
+    growing_classes?: string[] | undefined;
+    round?: string | undefined;
+    fixed_behind?: string | undefined;
+}>;
+type ImportedFinding = z.infer<typeof IMPORTED_FINDING_SCHEMA>;
+export declare function importFindings(index: FindingIndex, incoming: ImportedFinding[]): {
+    imported: number;
+    updated: number;
+    skipped: string[];
+};
+/**
+ * Normalize a retainer path into a signature that is stable across captures.
+ *
+ * Strips exactly the things that differ per capture and nothing else:
+ *  - `@12345` node ids, including the ` @…`-suffixed Context/scope names;
+ *  - numeric array indices (`[47]`, `.47`), which depend on insertion order;
+ *  - hex/long digit runs inside names (ids embedded in keys, e.g. a chat id).
+ */
+export declare function normalizeRetainerPath(raw: string): string;
+export declare function fingerprintOf(signature: string, classes: string[]): string;
+/**
+ * Artifact families every hunt re-derives, seeded into a fresh index.
+ *
+ * An empty index answers NEW to everything — including populations that are
+ * documented, well understood, and not app memory at all. That makes the first
+ * `check` of a workstream actively misleading rather than merely unhelpful, and
+ * hand-seeding never happens because it is a step nobody is prompted to take.
+ *
+ * These entries are deliberately the GENERIC, tool-detectable families (the
+ * same taxonomy `artifact-classes.ts` classifies, plus the two dev-build
+ * registries `dev_artifacts` detects). They are marked `known` rather than
+ * `fixed`: they are not defects to be fixed, they are populations a hunt must
+ * subtract. Anything app-specific belongs in a real `action: "import"`.
+ */
+export declare function builtinSeedFindings(): ImportedFinding[];
+/**
+ * Known entries that share a growing class with the candidate.
+ *
+ * The fingerprint is an EXACT match on signature + class set, which is right for
+ * "have we filed this before" and useless for "is this population a known
+ * artifact". Measured against a freshly-seeded index: a realistic check —
+ * retainer path `(GC roots) > (Global handles) > Object.allSignaturesByType`,
+ * growing class `allSignaturesByType` — returned NEW, even though the React Fast
+ * Refresh registry entry naming that exact class was sitting in the index. A
+ * caller has to reproduce the seeded signature string verbatim to get a hit,
+ * which nobody will ever do, so without this the seeding is decorative.
+ *
+ * Reported ALONGSIDE the NEW verdict rather than replacing it: a class overlap
+ * is a lead, not an identification, and silently converting NEW to KNOWN on one
+ * shared class name would suppress real findings.
+ */
+export declare function relatedByClass(index: FindingIndex, classes: readonly string[], excludeFingerprint: string): Finding[];
+/**
+ * Does the index hold anything beyond the generic built-in artifact families?
+ *
+ * `loadIndex` seeds a fresh index with those families, so a plain
+ * `Object.keys(findings).length === 0` is never true and every "is this index
+ * usable" guard built on it silently never fires. The question that actually
+ * matters is whether the index carries history for THIS app; built-in entries
+ * are stamped `first_seen_round: 'builtin'` and say nothing about it.
+ */
+export declare function hasAppHistory(index: {
+    findings: Record<string, {
+        first_seen_round: string;
+    }>;
+}): boolean;
+/**
+ * Fingerprint a candidate and look it up, for callers that are not the
+ * `memlab_finding_index` tool itself.
+ *
+ * Exists because the index only prevents re-discovery if somebody remembers to
+ * consult it, and in practice nobody does: a measured session produced three
+ * findings that were all already fixed behind gates, and never called `check`
+ * once. The tools that actually surface findings — `auto_investigate`,
+ * `leak_report` — now annotate inline instead of relying on that recall.
+ *
+ * Returns `indexEmpty` so the caller can say the verdict means nothing rather
+ * than printing a confident NEW from an index that has never been seeded.
+ */
+export type FindingLookup = {
+    verdict: 'NEW' | 'KNOWN' | 'KNOWN-AND-FIXED';
+    fixedBehind?: string;
+    note?: string;
+    round?: string;
+    related: string[];
+    indexEmpty: boolean;
+    indexPath: string;
+};
+/**
+ * The index, read once, for callers that look up many candidates in a row.
+ *
+ * `lookupFinding` reads and parses the index file on every call, which is
+ * fine for a one-off check and wasteful inside a report loop that annotates
+ * every finding — that turns one read into N reads of the same file.
+ */
+export type LoadedFindingIndex = {
+    index: FindingIndex;
+    indexPath: string;
+};
+export declare function loadFindingIndex(workstream?: string): LoadedFindingIndex;
+export declare function lookupFinding(retainerPath: string, classes: readonly string[], workstream?: string): FindingLookup;
+export declare function lookupFindingIn(loaded: LoadedFindingIndex, retainerPath: string, classes: readonly string[]): FindingLookup;
+/** One-line renderer for an inline verdict badge. */
+export declare function renderFindingVerdict(l: FindingLookup): string;
+/**
+ * The banner to print once per report when the index cannot support a verdict.
+ */
+export declare function findingIndexEmptyBanner(indexPath: string): string;
+export declare function registerFindingIndex(server: McpServer): void;
+export {};
+//# sourceMappingURL=finding-index.d.ts.map