@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/trace-all.js

@@ -0,0 +1,263 @@
+/**
+ * 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 memlabCore from '@memlab/core';
+import { z } from 'zod';
+import { getSnapshot, getSnapshotMetadata } from '../heap-state.js';
+import { formatTraceChain, getRetainerTrace, traceToKey, } from './retainer-summary.js';
+import { boundedDominatorRetainedSize, errorResult, formatBytes, formatNumber, markdownTable, toolResult, } from '../utils.js';
+const { NumericSet } = memlabCore;
+// Tracing is a pointer walk per node, so the whole population is affordable at
+// heap scale — but not without a bound, because a pathological graph turns it
+// into the load-time dominator pass all over again.
+const DEFAULT_MAX_TRACE = 200000;
+const MAX_IDS_PER_CLUSTER = 50000;
+/**
+ * Render a cluster's chain. When a path was truncated for grouping, its last
+ * step still carries the edge leading to the next hop, and that edge IS part
+ * of the grouping key — so suppressing it (which is correct for a complete
+ * path, whose last node is the target) renders two distinct clusters
+ * byte-identically. Show it, with a marker for the hops beyond.
+ */
+export function renderClusterChain(steps) {
+    const base = formatTraceChain(steps);
+    const last = steps[steps.length - 1];
+    return last?.edgeName != null ? `${base} --${last.edgeName}--> ⋯` : base;
+}
+export function selectPopulation(snapshot, sel) {
+    const out = [];
+    if (sel.nodeIds != null && sel.nodeIds.length > 0) {
+        for (const id of sel.nodeIds) {
+            const n = snapshot.getNodeById(id);
+            if (n != null)
+                out.push(n);
+        }
+        return out;
+    }
+    const want = sel.shape != null ? new Set(sel.shape) : null;
+    snapshot.nodes.forEach(node => {
+        if (node.id <= 3)
+            return;
+        if (sel.className != null) {
+            if (node.name !== sel.className)
+                return;
+        }
+        else if (want != null) {
+            const remaining = new Set(want);
+            for (const e of node.references) {
+                if (e.type !== 'property')
+                    continue;
+                remaining.delete(String(e.name_or_index));
+                if (remaining.size === 0)
+                    break;
+            }
+            if (remaining.size > 0)
+                return;
+        }
+        out.push(node);
+    });
+    return out;
+}
+export function clusterByRetainerPath(nodes, frameworkFilter, maxTrace, 
+// Hops from the GC root to key on. Paths are root-first, so truncating keeps
+// the owner side and collapses per-instance leaves — the difference between
+// "one owner, 40,000 objects" and 26,000 one-object paths that differ only
+// in which array index they sit at.
+maxDepth) {
+    const byKey = new Map();
+    let traced = 0;
+    let noPath = 0;
+    let truncated = false;
+    for (const node of nodes) {
+        if (traced + noPath >= maxTrace) {
+            truncated = true;
+            break;
+        }
+        const steps = getRetainerTrace(node);
+        if (steps == null) {
+            noPath++;
+            continue;
+        }
+        traced++;
+        const keySteps = maxDepth != null && maxDepth > 0 && maxDepth < steps.length
+            ? steps.slice(0, maxDepth)
+            : steps;
+        const key = traceToKey(keySteps, frameworkFilter);
+        const existing = byKey.get(key);
+        if (existing != null) {
+            existing.count++;
+            existing.selfSize += node.self_size;
+            if (existing.exampleIds.length < 3)
+                existing.exampleIds.push(node.id);
+            if (existing.ids.length < MAX_IDS_PER_CLUSTER)
+                existing.ids.push(node.id);
+            else
+                existing.idsTruncated = true;
+        }
+        else {
+            byKey.set(key, {
+                key,
+                steps: keySteps,
+                count: 1,
+                selfSize: node.self_size,
+                exampleIds: [node.id],
+                ids: [node.id],
+                idsTruncated: false,
+            });
+        }
+    }
+    const clusters = [...byKey.values()].sort((a, b) => b.count - a.count);
+    return { clusters, traced, noPath, truncated };
+}
+export function registerTraceAll(server) {
+    server.tool('memlab_trace_all', 'Retainer-trace an ENTIRE population and cluster the paths server-side, instead of sampling a handful and hoping they are representative.\n\n' +
+        '`memlab_retainer_summary` samples ~10 instances and stops early once they agree, which is the right default for a quick read but is structurally unable to find a minority path: a cluster holding 3% of the objects and 60% of the bytes is invisible to it, and that cluster is very often the leak. This traces every member (bounded, and it says so when the bound is hit), groups by structural path signature, and reports each cluster with its share of the population — so the output cost is the number of DISTINCT paths, not the size of the population.\n\n' +
+        'Select by class, shape or explicit ids. Use it when a population is large enough that "are they all retained the same way?" is the question, and when a sampled answer has already been used to justify a conclusion.', {
+        class_name: z
+            .string()
+            .optional()
+            .describe('Trace every instance of this class (exact name match).'),
+        shape: z
+            .array(z.string())
+            .optional()
+            .describe('Trace every object carrying ALL of these properties — the usable selector on a minified heap.'),
+        node_ids: z
+            .array(z.number())
+            .optional()
+            .describe('Trace exactly these node ids.'),
+        framework_filter: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Collapse V8/framework internals (system / Context, PromiseReaction, …) out of the grouping key so structurally identical application paths cluster together (default true).'),
+        limit: z
+            .number()
+            .optional()
+            .default(8)
+            .describe('Clusters to render in full (default 8).'),
+        exact_bytes: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Compute dominator-deduped retained bytes for each rendered cluster (default true). Turn off on very large populations if the walk is slow; self size is always reported.'),
+        max_depth: z
+            .number()
+            .optional()
+            .describe('Group on the first N hops from the GC ROOT instead of the whole path. Defaults to the whole path, which is exact but fragments when the leaf hop is per-instance — a per-chat property edge or a per-event listener array gives nearly one path per object. Try 5-7 to see owners rather than instances.'),
+        max_trace: z
+            .number()
+            .optional()
+            .default(DEFAULT_MAX_TRACE)
+            .describe(`Safety bound on how many nodes to trace (default ${formatNumber(DEFAULT_MAX_TRACE)}). Truncation is always reported — a partial sweep is never presented as a complete one.`),
+    }, async ({ class_name, shape, node_ids, framework_filter, limit, exact_bytes, max_depth, max_trace, }) => {
+        try {
+            const snapshot = getSnapshot();
+            const selectors = [
+                class_name != null,
+                shape != null && shape.length > 0,
+                node_ids != null && node_ids.length > 0,
+            ].filter(Boolean).length;
+            if (selectors !== 1) {
+                return errorResult(new Error('Pass exactly one of class_name / shape / node_ids — combining them would make the reported population ambiguous.'));
+            }
+            const nodes = selectPopulation(snapshot, {
+                nodeIds: node_ids,
+                className: class_name,
+                shape,
+            });
+            if (nodes.length === 0) {
+                return toolResult('Nothing matched. Check the class name with `memlab_class_histogram` or the shape with `memlab_shape_histogram`.');
+            }
+            const { clusters, traced, noPath, truncated } = clusterByRetainerPath(nodes, framework_filter, max_trace, max_depth);
+            if (clusters.length === 0) {
+                return toolResult(`All ${formatNumber(nodes.length)} matched objects have no retainer path — they are unreachable and awaiting collection, not retained. Nothing to trace.`);
+            }
+            const label = class_name != null
+                ? `class \`${class_name}\``
+                : shape != null
+                    ? `shape \`{${shape.join(', ')}}\``
+                    : `${formatNumber(nodes.length)} explicit id(s)`;
+            const meta = getSnapshotMetadata();
+            const rendered = clusters.slice(0, limit);
+            const bytesByKey = new Map();
+            if (exact_bytes) {
+                for (const c of rendered) {
+                    // Only the rendered clusters get the dominator walk: it is the
+                    // expensive part, and a cluster nobody sees does not need a number
+                    // attached to it. Member ids were collected during the single
+                    // clustering pass, so this does not re-walk the population.
+                    const bytes = boundedDominatorRetainedSize(new NumericSet(c.ids), snapshot);
+                    bytesByKey.set(c.key, {
+                        retained: bytes.retained,
+                        exact: bytes.exact && !c.idsTruncated,
+                    });
+                }
+            }
+            const totalTraced = traced;
+            const rows = rendered.map((c, i) => {
+                const bytes = bytesByKey.get(c.key);
+                return [
+                    String(i + 1),
+                    formatNumber(c.count),
+                    `${((c.count / totalTraced) * 100).toFixed(1)}%`,
+                    formatBytes(c.selfSize),
+                    bytes != null
+                        ? `${formatBytes(bytes.retained)}${bytes.exact ? '' : ' (ub)'}`
+                        : '—',
+                    `@${c.exampleIds[0]}`,
+                ];
+            });
+            const lines = [
+                `## Retainer paths for ${label}`,
+                '',
+                `**${formatNumber(traced)} of ${formatNumber(nodes.length)} traced** into **${formatNumber(clusters.length)} distinct path${clusters.length === 1 ? '' : 's'}**` +
+                    `${noPath > 0 ? `; ${formatNumber(noPath)} had no retainer path (unreachable, awaiting collection)` : ''}` +
+                    `${truncated ? `. ⚠ Stopped at the ${formatNumber(max_trace)}-node bound, so this is a partial sweep — raise max_trace for the full population` : ''}.`,
+                '',
+                markdownTable(['#', 'Objects', 'Share', 'Self size', 'Retained', 'Example'], rows, new Set([1, 2, 3, 4])),
+            ];
+            // A path count close to the population count means the signature is
+            // keying on something per-instance, and every cluster is a single
+            // object wearing a path. That reads as "no dominant owner" when the
+            // truth may be one owner and a per-instance leaf hop.
+            if (max_depth == null && clusters.length > totalTraced * 0.5) {
+                lines.push('', `⚠ ${formatNumber(clusters.length)} paths for ${formatNumber(totalTraced)} objects — the full-depth signature is keying on a per-instance hop (a per-chat property edge, a per-event listener array), so almost every object is its own "path". Re-run with \`max_depth: 5\` (or 6-7) to group on the owner side of the chain instead. Shares below are computed over this fragmented grouping and should not be read as "no dominant owner".`);
+            }
+            if (clusters.length > rendered.length) {
+                const rest = clusters.slice(rendered.length);
+                const restCount = rest.reduce((a, c) => a + c.count, 0);
+                lines.push('', `_${formatNumber(clusters.length - rendered.length)} further path(s) hold ${formatNumber(restCount)} object(s) (${((restCount / totalTraced) * 100).toFixed(1)}%); raise \`limit\` to render them._`);
+            }
+            // The whole point of a full sweep is that it can see what sampling
+            // cannot, so say when it did.
+            const minority = clusters.filter(c => c.count / totalTraced < 0.1 && c.count > 0);
+            if (clusters.length > 1) {
+                const dominant = clusters[0];
+                const dominantShare = (dominant.count / totalTraced) * 100;
+                lines.push('', dominantShare >= 95
+                    ? `**One path dominates** (${dominantShare.toFixed(1)}%): a single retention mechanism, and a fix at that owner addresses effectively the whole population.`
+                    : `**Retention is split across ${formatNumber(clusters.length)} paths**, the largest holding ${dominantShare.toFixed(1)}%. A fix aimed at one owner leaves the rest — size it against the cluster, not the class total.`);
+                if (minority.length > 0) {
+                    const minCount = minority.reduce((a, c) => a + c.count, 0);
+                    lines.push('', `⚠ ${formatNumber(minority.length)} path(s) below 10% share, holding ${formatNumber(minCount)} object(s) in total. A 10-instance sample would very likely have missed every one of them; check whether any is the interesting one before concluding the population is homogeneous.`);
+                }
+            }
+            rendered.forEach((c, i) => {
+                const bytes = bytesByKey.get(c.key);
+                lines.push('', `### Path ${i + 1} — ${formatNumber(c.count)} object(s), ${((c.count / totalTraced) * 100).toFixed(1)}%${bytes != null ? `, ${formatBytes(bytes.retained)} retained` : ''}`, '', renderClusterChain(c.steps), '', `Examples: ${c.exampleIds.map(id => `@${id}`).join(', ')}`);
+            });
+            lines.push('', `_Paths are grouped by structural signature${framework_filter ? ' with framework internals collapsed' : ''}; per-instance node ids in V8 internal names are normalized out, so two rows are never byte-identical. Retained bytes are dominator-deduped within a cluster and do not add up across clusters when one cluster dominates another._`, '', `Next: \`memlab_what_if\` to size a fix at one owner, \`memlab_identify\` to name the population, \`memlab_retainer_diff\` to see whether these paths are the ones that grew.${meta != null ? '' : ''}`);
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=trace-all.js.map

package/dist/tools/trace-all.js.map

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

package/dist/tools/unit-cost.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 registerUnitCost(server: McpServer): void;
+//# sourceMappingURL=unit-cost.d.ts.map

package/dist/tools/unit-cost.d.ts.map

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

package/dist/tools/unit-cost.js

@@ -0,0 +1,219 @@
+/**
+ * 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 memlabCore from '@memlab/core';
+import { z } from 'zod';
+import { getCurrentHandle, getMetadataByHandle, getSnapshot, getSnapshotByHandle, } from '../heap-state.js';
+import { boundedDominatorRetainedSize, errorResult, formatBytes, formatNumber, markdownTable, toolResult, } from '../utils.js';
+const { NumericSet } = memlabCore;
+function matchesShape(node, shape) {
+    if (shape.length === 0)
+        return false;
+    const want = new Set(shape);
+    for (const e of node.references) {
+        if (e.type !== 'property')
+            continue;
+        want.delete(String(e.name_or_index));
+        if (want.size === 0)
+            return true;
+    }
+    return false;
+}
+function measure(snapshot, opts) {
+    const ids = [];
+    // Sizing a cap needs the per-entry cost of THAT cache, not of a class that
+    // happens to include its entries alongside thousands of unrelated objects.
+    // The entries of one container are the population the cap actually bounds.
+    if (opts.containerId != null) {
+        const container = snapshot.getNodeById(opts.containerId);
+        if (container == null)
+            return { count: 0, retained: 0, exact: true };
+        const seen = new Set();
+        for (const edge of container.references) {
+            if (edge.type !== 'element' && edge.type !== 'property')
+                continue;
+            const name = String(edge.name_or_index);
+            // Structural properties are not entries; counting them inflates the
+            // denominator and understates the per-entry cost.
+            if (edge.type === 'property' &&
+                (name === 'length' ||
+                    name === 'size' ||
+                    name === '__proto__' ||
+                    name.startsWith('_'))) {
+                continue;
+            }
+            const target = edge.toNode;
+            if (target.id <= 3 || seen.has(target.id))
+                continue;
+            seen.add(target.id);
+            ids.push(target.id);
+        }
+        if (ids.length === 0)
+            return { count: 0, retained: 0, exact: true };
+        const { retained, exact } = boundedDominatorRetainedSize(new NumericSet(ids), snapshot);
+        return { count: ids.length, retained, exact };
+    }
+    snapshot.nodes.forEach(node => {
+        if (node.id <= 3)
+            return;
+        if (opts.className != null) {
+            if (node.name !== opts.className)
+                return;
+        }
+        else if (opts.shape != null) {
+            if (!matchesShape(node, opts.shape))
+                return;
+        }
+        ids.push(node.id);
+    });
+    if (ids.length === 0)
+        return { count: 0, retained: 0, exact: true };
+    const { retained, exact } = boundedDominatorRetainedSize(new NumericSet(ids), snapshot);
+    return { count: ids.length, retained, exact };
+}
+export function registerUnitCost(server) {
+    server.tool('memlab_unit_cost', 'How much memory does ONE of these actually cost? Reports dominator-deduped retained bytes per instance for a class or an object shape, ' +
+        'and — given two snapshots — separates the AVERAGE from the MARGINAL cost.\n\n' +
+        'That distinction decides fixes. A population whose first instances drag in shared structure has a high average and a low marginal cost, ' +
+        'so capping it saves far less than the average implies; a population with a flat per-instance cost scales linearly and a cap saves exactly ' +
+        'what the arithmetic says. Sizing an LRU, an undo-stack cap, an eviction policy or a "is this worth interning?" decision all need the ' +
+        'marginal number, and computing it by hand means four calls and a subtraction that is easy to get backwards.\n\n' +
+        'With one snapshot you get the average and a projection table. With `baseline_handle` you also get the marginal cost between the two rungs.', {
+        class_name: z
+            .string()
+            .optional()
+            .describe('Class/constructor name as reported by memlab_class_histogram (exact match). Use this OR shape.'),
+        shape: z
+            .array(z.string())
+            .optional()
+            .describe('Property names an instance must ALL carry, e.g. ["callback","context"]. Use for minified heaps where the class name is meaningless. Use this OR class_name.'),
+        handle: z
+            .string()
+            .optional()
+            .describe('Snapshot to measure (defaults to the active one).'),
+        baseline_handle: z
+            .string()
+            .optional()
+            .describe('Earlier snapshot. When given, the marginal cost is (retained_now − retained_baseline) / (count_now − count_baseline) — what one MORE instance costs, which is the number a cap or eviction policy is sized against.'),
+        container_id: z
+            .number()
+            .optional()
+            .describe('Measure the ENTRIES of this container (a Map, Set, Array or plain-object cache from memlab_cache_analysis) instead of a class or shape. This is the population an LRU cap actually bounds, so it is the right denominator when sizing one — a class-wide average mixes in instances the cache does not hold. Structural properties (length, size, _-prefixed) are excluded from the entry count.'),
+        project_caps: z
+            .array(z.number())
+            .optional()
+            .describe('Instance counts to project retained size for, e.g. [100, 500, 2000] when choosing a cache cap. Uses the marginal cost when available, otherwise the average (and says which).'),
+    }, async ({ class_name, shape, container_id, handle, baseline_handle, project_caps, }) => {
+        try {
+            if (container_id == null &&
+                class_name == null &&
+                (shape == null || shape.length === 0)) {
+                return errorResult(new Error('Pass class_name, shape or container_id. On a minified heap prefer shape — class names like "t"/"e" match thousands of unrelated objects — and prefer container_id when sizing a cap for one specific cache.'));
+            }
+            if (class_name != null && shape != null && shape.length > 0) {
+                return errorResult(new Error('Pass class_name OR shape, not both.'));
+            }
+            const target = handle != null ? getSnapshotByHandle(handle) : getSnapshot();
+            if (target == null) {
+                return errorResult(new Error(`Snapshot "${handle}" is not resident.`));
+            }
+            const targetLabel = handle ?? getCurrentHandle() ?? '(active)';
+            if (container_id != null && baseline_handle != null) {
+                return errorResult(new Error('container_id cannot be combined with baseline_handle: node ids are per-capture, so the same id in the baseline is a different object (or nothing) and the marginal cost would be computed from two unrelated populations. Select the container in each snapshot separately, or use a shape.'));
+            }
+            const now = measure(target, {
+                className: class_name,
+                shape,
+                containerId: container_id,
+            });
+            if (now.count === 0) {
+                return toolResult(`No instances found for ${container_id != null ? `the entries of @${container_id}` : class_name != null ? `class \`${class_name}\`` : `shape {${(shape ?? []).join(', ')}}`} in \`${targetLabel}\`. ` +
+                    'For a class, check the exact name with memlab_class_histogram; for a shape, with memlab_shape_histogram.');
+            }
+            const average = now.retained / now.count;
+            let marginal = null;
+            let base = null;
+            if (baseline_handle != null) {
+                const baseSnapshot = getSnapshotByHandle(baseline_handle);
+                if (baseSnapshot == null) {
+                    return errorResult(new Error(`Baseline snapshot "${baseline_handle}" is not resident.`));
+                }
+                base = measure(baseSnapshot, {
+                    className: class_name,
+                    shape,
+                    // Node ids are per-capture, so a container selected by id in one
+                    // snapshot is a different object (or nothing) in another. Refusing
+                    // is the only honest option; silently measuring whatever holds
+                    // that id in the baseline would produce a marginal cost computed
+                    // from two unrelated populations.
+                    containerId: undefined,
+                });
+                const dCount = now.count - base.count;
+                const dBytes = now.retained - base.retained;
+                if (dCount > 0)
+                    marginal = dBytes / dCount;
+            }
+            const label = container_id != null
+                ? `entries of @${container_id}`
+                : class_name != null
+                    ? `class \`${class_name}\``
+                    : `shape \`{${(shape ?? []).join(', ')}}\``;
+            const lines = [
+                `## Unit cost — ${label}`,
+                '',
+                `\`${targetLabel}\`${getMetadataByHandle(targetLabel) ? ` (${getMetadataByHandle(targetLabel)?.fileName})` : ''}: ` +
+                    `**${formatNumber(now.count)} instances retaining ${formatBytes(now.retained)}**${now.exact ? '' : ' (upper bound — the dominator walk hit its depth cap)'}.`,
+                '',
+                `- **Average**: ${formatBytes(Math.round(average))} per instance.`,
+            ];
+            if (base != null && marginal != null) {
+                lines.push(`- **Marginal**: ${formatBytes(Math.round(marginal))} per instance — measured across ${formatNumber(now.count - base.count)} added instances between \`${baseline_handle}\` (${formatNumber(base.count)} / ${formatBytes(base.retained)}) and \`${targetLabel}\`.`);
+                const ratio = average > 0 ? marginal / average : 1;
+                if (ratio < 0.6) {
+                    lines.push('', `⚠ Marginal is ${(ratio * 100).toFixed(0)}% of average: much of what this population retains is **shared structure the first instances pulled in**, not per-instance data. Size any cap or eviction policy on the marginal figure — the average overstates what capping saves.`);
+                }
+                else if (ratio > 1.4) {
+                    lines.push('', `⚠ Marginal is ${(ratio * 100).toFixed(0)}% of average: later instances cost MORE than earlier ones (they are retaining progressively more, or a shared structure is growing with them). Check whether the cost per instance is itself unbounded before sizing a cap.`);
+                }
+                else {
+                    lines.push('', '_Marginal ≈ average: the population scales linearly, so a cap saves what the arithmetic says._');
+                }
+            }
+            else if (baseline_handle != null) {
+                lines.push('', '_No marginal cost: the population did not grow between the two snapshots, so there is no delta to divide._');
+            }
+            else {
+                lines.push('', '_Average only. Pass `baseline_handle` (an earlier rung) for the marginal cost — the two differ whenever the first instances drag in shared structure, and it is the marginal one that sizes a fix._');
+            }
+            if (project_caps != null && project_caps.length > 0) {
+                const unit = marginal ?? average;
+                const usingMarginal = marginal != null;
+                lines.push('', `### Projected retained size at a cap (using the ${usingMarginal ? 'marginal' : 'average'} cost)`, '');
+                const rows = [...project_caps]
+                    .sort((a, b) => b - a)
+                    .map(cap => {
+                    const projected = Math.round(unit * Math.min(cap, now.count));
+                    const saved = Math.round(Math.max(0, now.retained - unit * cap));
+                    return [
+                        formatNumber(cap),
+                        formatBytes(projected),
+                        cap >= now.count ? '—' : formatBytes(saved),
+                    ];
+                });
+                lines.push(markdownTable(['Cap (instances)', 'Projected retained', 'Saved vs today'], rows, new Set([0, 1, 2])));
+                lines.push('', '_A projection, not a measurement: it assumes the per-instance cost holds at the cap and that evicted values are not co-retained elsewhere. Confirm the top candidate with `memlab_what_if` or a capped re-run._');
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=unit-cost.js.map

package/dist/tools/unit-cost.js.map

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

package/dist/tools/verify-fix.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 { IHeapSnapshot } from '@memlab/core';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type MetricKind = 'collection_length' | 'class_count' | 'pending_chain';
+/**
+ * Measure the metric on one parsed snapshot. One scalar per snapshot is the
+ * whole point: the arms are compared on a rate, and a rate needs a number per
+ * rung, not a report.
+ */
+export declare function measureMetric(snapshot: IHeapSnapshot, kind: MetricKind, locator: string, chainEdge: string): number;
+/** Growth per interaction cycle across an arm's ladder. */
+export declare function perCycleRate(values: number[], cycles: number): number;
+export declare function registerVerifyFix(server: McpServer): void;
+export {};
+//# sourceMappingURL=verify-fix.d.ts.map

package/dist/tools/verify-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-fix.d.ts","sourceRoot":"","sources":["../../src/tools/verify-fix.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAY,aAAa,EAAC,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAiBvE,KAAK,UAAU,GAAG,mBAAmB,GAAG,aAAa,GAAG,eAAe,CAAC;AAOxE;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAuCR;AA4CD,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoKzD"}