@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/progress.js

@@ -0,0 +1,46 @@
+/**
+ * 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
+ */
+const NOOP = {
+    phase: () => {
+        // No progress channel and no stderr labelling to do for a caller that
+        // supplied no `extra` (in-process dispatch); reporting is simply off.
+    },
+};
+/**
+ * Build a reporter from a tool handler's `extra` argument.
+ *
+ * Tolerates a missing or empty `extra`: tools dispatched in-process by
+ * `memlab_batch` are called with `{}`, and a reporter that threw there would
+ * turn a progress nicety into a batch-wide failure.
+ */
+export function makeProgressReporter(extra, label) {
+    if (extra == null || typeof extra !== 'object')
+        return NOOP;
+    const e = extra;
+    const token = e._meta?.progressToken;
+    const send = typeof e.sendNotification === 'function' ? e.sendNotification : null;
+    return {
+        phase(step, total, message) {
+            process.stderr.write(`[${label} ${step}/${total}] ${message}\n`);
+            if (send == null || token == null)
+                return;
+            // Fire-and-forget: a client that cannot accept the notification must not
+            // fail the operation the notification is about.
+            void send({
+                method: 'notifications/progress',
+                params: { progressToken: token, progress: step, total, message },
+            }).catch(() => {
+                // Swallowed on purpose: a client that rejects the notification must not
+                // fail the operation the notification is merely describing.
+            });
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6CH,MAAM,IAAI,GAAqB;IAC7B,KAAK,EAAE,GAAG,EAAE;QACV,sEAAsE;QACtE,sEAAsE;IACxE,CAAC;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,KAAa;IAEb,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,CAAC,GAAG,KAA6B,CAAC;IACxC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC;IACrC,MAAM,IAAI,GACR,OAAO,CAAC,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvE,OAAO;QACL,KAAK,CAAC,IAAY,EAAE,KAAa,EAAE,OAAe;YAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC;YACjE,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI;gBAAE,OAAO;YAC1C,yEAAyE;YACzE,gDAAgD;YAChD,KAAK,IAAI,CAAC;gBACR,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE,EAAC,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAC;aAC/D,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACZ,wEAAwE;gBACxE,4DAA4D;YAC9D,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/react-shapes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+/**
+ * Recognising React structures in a heap snapshot.
+ *
+ * Fibers, hooks, update queues and update records are ALL plain `Object` in a
+ * production bundle, so every class-name-based heuristic walks straight past
+ * them. On one population `helpers.owner()` returned `(none)` for 100% of
+ * 1,645 records for exactly this reason, and the useful answer —
+ * `BaseTooltipSimple` — needed a hand-written walk to the fiber plus a read of
+ * `elementType`.
+ *
+ * That walk has now been hand-written for four findings of the same family
+ * across this workstream. The `elementType` / `stateNode` / `memoizedProps`
+ * layout is stable across every React version Meta ships, so it belongs here
+ * rather than in each investigation.
+ */
+import type { IHeapNode } from '@memlab/core';
+/** Property set of a React update record — the eager-bailout leak family. */
+export declare const UPDATE_RECORD_FIELDS: string[];
+/** Does this node look like a React fiber? */
+export declare function isFiberNode(node: IHeapNode): boolean;
+/** Does this node look like a React update record (`queue.pending` member)? */
+export declare function isUpdateRecord(node: IHeapNode): boolean;
+/**
+ * The component name behind a fiber.
+ *
+ * Three shapes, in the order they occur: `elementType` is a closure (function
+ * component — the closure's own name is the component name), or a string (host
+ * element), or an object carrying `render` / `type` (memo, forwardRef, lazy),
+ * in which case the name is one level deeper.
+ */
+export declare function fiberComponentName(fiber: IHeapNode): string | null;
+export declare function nearestFiber(node: IHeapNode, maxHops: number): IHeapNode | null;
+//# sourceMappingURL=react-shapes.d.ts.map

package/dist/react-shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-shapes.d.ts","sourceRoot":"","sources":["../src/react-shapes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAe5C,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,UAMhC,CAAC;AAYF,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAOpD;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAWvD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAOlE;AAyCD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAsBlB"}

package/dist/react-shapes.js

@@ -0,0 +1,149 @@
+/**
+ * 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
+ */
+/**
+ * Fields that only a fiber carries. `stateNode` alone is too weak (a class
+ * instance has one), so a match needs `elementType` or `memoizedProps`, which
+ * together with `return`/`child` are fiber-specific.
+ */
+const FIBER_STRONG_FIELDS = ['elementType', 'memoizedProps', 'pendingProps'];
+const FIBER_SUPPORTING_FIELDS = [
+    'return',
+    'child',
+    'stateNode',
+    'memoizedState',
+];
+/** Property set of a React update record — the eager-bailout leak family. */
+export const UPDATE_RECORD_FIELDS = [
+    'action',
+    'eagerState',
+    'hasEagerState',
+    'lane',
+    'next',
+];
+/** Own property names of a node, as a Set. Cheap; used by every check here. */
+function propertyNames(node) {
+    const names = new Set();
+    for (const edge of node.references) {
+        if (edge.type !== 'property')
+            continue;
+        names.add(String(edge.name_or_index));
+    }
+    return names;
+}
+/** Does this node look like a React fiber? */
+export function isFiberNode(node) {
+    if (node.type !== 'object')
+        return false;
+    const names = propertyNames(node);
+    const strong = FIBER_STRONG_FIELDS.filter(f => names.has(f)).length;
+    if (strong === 0)
+        return false;
+    const supporting = FIBER_SUPPORTING_FIELDS.filter(f => names.has(f)).length;
+    return strong + supporting >= 3;
+}
+/** Does this node look like a React update record (`queue.pending` member)? */
+export function isUpdateRecord(node) {
+    if (node.type !== 'object')
+        return false;
+    const names = propertyNames(node);
+    // `eagerState` may be absent when the update never took the eager path, so
+    // require the rest and treat it as optional.
+    return (names.has('action') &&
+        names.has('lane') &&
+        names.has('next') &&
+        (names.has('hasEagerState') || names.has('eagerState')));
+}
+/**
+ * The component name behind a fiber.
+ *
+ * Three shapes, in the order they occur: `elementType` is a closure (function
+ * component — the closure's own name is the component name), or a string (host
+ * element), or an object carrying `render` / `type` (memo, forwardRef, lazy),
+ * in which case the name is one level deeper.
+ */
+export function fiberComponentName(fiber) {
+    for (const edge of fiber.references) {
+        if (edge.type !== 'property')
+            continue;
+        if (String(edge.name_or_index) !== 'elementType')
+            continue;
+        return elementTypeName(edge.toNode, 0);
+    }
+    return null;
+}
+function elementTypeName(node, depth) {
+    if (depth > 2)
+        return null;
+    if (node.type === 'string' || node.type === 'concatenated string') {
+        const value = node.toStringNode()?.stringValue ?? node.name;
+        return value ? `<${value}>` : null;
+    }
+    if (node.type === 'closure') {
+        // A minified bundle still names the closure after the component in the
+        // overwhelming majority of cases; an empty name is worth reporting as
+        // unknown rather than as "".
+        return node.name && node.name !== 'function' ? node.name : null;
+    }
+    // memo / forwardRef / lazy wrappers.
+    for (const edge of node.references) {
+        if (edge.type !== 'property')
+            continue;
+        const name = String(edge.name_or_index);
+        if (name !== 'render' && name !== 'type')
+            continue;
+        const inner = elementTypeName(edge.toNode, depth + 1);
+        if (inner != null)
+            return inner;
+    }
+    return null;
+}
+/**
+ * Walk up from a hook/queue/record to the fiber that owns it.
+ *
+ * Prefers the edges that actually lead there — a hook's owner is reached via
+ * `memoizedState` / `next` / `queue` / `baseQueue`, not by whatever referrer
+ * happens to come first — and falls back to any referrer so a slightly
+ * different shape still resolves.
+ */
+const OWNER_EDGE_PREFERENCE = [
+    'memoizedState',
+    'queue',
+    'baseQueue',
+    'next',
+    'return',
+];
+export function nearestFiber(node, maxHops) {
+    let current = node;
+    const seen = new Set([node.id]);
+    for (let hop = 0; hop < maxHops; hop++) {
+        if (isFiberNode(current))
+            return current;
+        let chosen = null;
+        let fallback = null;
+        for (const edge of current.referrers) {
+            const from = edge.fromNode;
+            if (from.id <= 3 || seen.has(from.id))
+                continue;
+            if (OWNER_EDGE_PREFERENCE.includes(String(edge.name_or_index))) {
+                chosen = from;
+                break;
+            }
+            if (fallback == null)
+                fallback = from;
+        }
+        const next = chosen ?? fallback;
+        if (next == null)
+            return null;
+        seen.add(next.id);
+        current = next;
+    }
+    return null;
+}
+//# sourceMappingURL=react-shapes.js.map

package/dist/react-shapes.js.map

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

package/dist/result-handles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+export declare function resolveSavedNodeIds(name: string): number[];
+//# sourceMappingURL=result-handles.d.ts.map

package/dist/result-handles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-handles.d.ts","sourceRoot":"","sources":["../src/result-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA+C1D"}

package/dist/result-handles.js

@@ -0,0 +1,77 @@
+/**
+ * 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 { getEvalScratch } from './heap-state.js';
+/**
+ * Read a saved result (from `memlab_eval`'s `save_as` / `helpers.save`) as a
+ * node-id list, so one tool's output can feed another's input without the ids
+ * making a round trip through the transcript.
+ *
+ * A list of a few thousand ids is tens of thousands of tokens to print and
+ * re-type, and re-typing them is where they get truncated or corrupted. The
+ * scratch store already existed for `eval`; this makes it readable by the tools
+ * that take `node_ids`, which is where such a list is actually wanted.
+ *
+ * Accepts the shapes a result realistically has: an array of numbers, an array
+ * of `{id}` objects, or an object with an `ids`/`node_ids` array.
+ */
+// `memlab_eval` namespaces saved values in the shared per-snapshot scratch so
+// they cannot collide with its own indexes. Reading them back means honoring
+// that prefix — a bare-name lookup finds nothing and reports "not saved" for a
+// result that is sitting right there.
+const SAVED_PREFIX = '__saved:';
+export function resolveSavedNodeIds(name) {
+    const scratch = getEvalScratch();
+    const prefixed = SAVED_PREFIX + name;
+    const key = prefixed in scratch ? prefixed : name;
+    if (!(key in scratch)) {
+        const available = Object.keys(scratch)
+            .filter(k => k.startsWith(SAVED_PREFIX))
+            .map(k => k.slice(SAVED_PREFIX.length));
+        throw new Error(`No saved result named "${name}". ` +
+            (available.length > 0
+                ? `Saved: ${available.join(', ')}.`
+                : 'Nothing is saved for this snapshot. Save one with memlab_eval({code, save_as: "name"}).') +
+            ' Saved results are per-snapshot and are dropped when the snapshot is replaced.');
+    }
+    const raw = scratch[key];
+    const fromArray = (arr) => {
+        const ids = [];
+        for (const item of arr) {
+            if (typeof item === 'number' && Number.isFinite(item)) {
+                ids.push(item);
+            }
+            else if (item != null && typeof item === 'object' && 'id' in item) {
+                const id = item.id;
+                if (typeof id === 'number')
+                    ids.push(id);
+            }
+        }
+        return ids;
+    };
+    let ids = [];
+    if (Array.isArray(raw)) {
+        ids = fromArray(raw);
+    }
+    else if (raw != null && typeof raw === 'object') {
+        const obj = raw;
+        const arr = Array.isArray(obj.ids)
+            ? obj.ids
+            : Array.isArray(obj.node_ids)
+                ? obj.node_ids
+                : null;
+        if (arr != null)
+            ids = fromArray(arr);
+    }
+    if (ids.length === 0) {
+        throw new Error(`Saved result "${name}" holds no node ids. Expected an array of ids, an array of objects with an \`id\` field, or an object with an \`ids\` array.`);
+    }
+    return ids;
+}
+//# sourceMappingURL=result-handles.js.map

package/dist/result-handles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-handles.js","sourceRoot":"","sources":["../src/result-handles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,sCAAsC;AACtC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;aACnC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,KAAK;YACjC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;gBACnB,CAAC,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACnC,CAAC,CAAC,yFAAyF,CAAC;YAC9F,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAY,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,CAAC,GAAc,EAAY,EAAE;QAC7C,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;YACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;iBAAM,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACpE,MAAM,EAAE,GAAI,IAAuB,CAAC,EAAE,CAAC;gBACvC,IAAI,OAAO,EAAE,KAAK,QAAQ;oBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,IAAI,GAAG,GAAa,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;SAAM,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,GAAG,GAAG,GAA0C,CAAC;QACvD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAChC,CAAC,CAAC,GAAG,CAAC,GAAG;YACT,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAC3B,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACd,CAAC,CAAC,IAAI,CAAC;QACX,IAAI,GAAG,IAAI,IAAI;YAAE,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,8HAA8H,CACpJ,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/server-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+/**
+ * The version this server reports about itself.
+ *
+ * Kept in its own module so `memlab_server_status` can report it without
+ * importing `index.ts` (which would be an import cycle — index imports every
+ * tool). Keep in sync with `package.json`; `scripts/check-version-sync.mjs`
+ * enforces that.
+ */
+export declare const SERVER_VERSION = "2.86.0";
+//# sourceMappingURL=server-version.d.ts.map

package/dist/server-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-version.d.ts","sourceRoot":"","sources":["../src/server-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC"}

package/dist/server-version.js

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+/**
+ * The version this server reports about itself.
+ *
+ * Kept in its own module so `memlab_server_status` can report it without
+ * importing `index.ts` (which would be an import cycle — index imports every
+ * tool). Keep in sync with `package.json`; `scripts/check-version-sync.mjs`
+ * enforces that.
+ */
+export const SERVER_VERSION = '2.86.0';
+//# sourceMappingURL=server-version.js.map

package/dist/server-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-version.js","sourceRoot":"","sources":["../src/server-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC"}

package/dist/snapshot-borrow.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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';
+/**
+ * Run `fn` against the snapshot at `localPath`, loading it only if it is not
+ * already resident, and leaving the session exactly as it was found.
+ *
+ * Every tool that walks an ORDERED ladder needs this, and each one getting it
+ * subtly wrong is the failure mode worth designing out. Three invariants:
+ *
+ *  - **Reuse a resident graph.** Re-parsing a 250 MB capture that is already in
+ *    memory is the single most expensive avoidable thing these tools do.
+ *  - **Hold one graph at a time.** `memlab_eval_across` needs every rung
+ *    resident simultaneously, which is precisely why it cannot serve a ladder of
+ *    large captures. Loading and dropping keeps peak RSS at one rung.
+ *  - **Restore the caller's active snapshot.** A ladder walk is a measurement,
+ *    not a navigation; silently leaving the session pointed at rung 6 makes the
+ *    caller's next `memlab_eval` answer a question about the wrong capture, and
+ *    nothing in that output says so.
+ */
+export declare function withSnapshotAt<T>(localPath: string, fn: (snapshot: IHeapSnapshot) => Promise<T> | T): Promise<T>;
+export interface ResolvedRung {
+    /** The path as the caller wrote it, used in report rows. */
+    label: string;
+    localPath: string;
+    sizeMB: number;
+}
+/**
+ * Resolve every path and check its size BEFORE anything is loaded.
+ *
+ * Ordering matters here: an unreadable or oversized rung five should fail in a
+ * second, not after four multi-minute loads have already been paid for.
+ */
+export declare function resolveRungs(paths: string[], maxFileSizeMB?: number): {
+    rungs: ResolvedRung[];
+    largestMB: number;
+};
+/**
+ * A full-heap walk on a multi-million-node graph does not finish inside the
+ * 60 s eval default, and every caller discovering that by timing out first is
+ * pure friction. Scale from the largest rung.
+ */
+export declare function scaledTimeoutMs(largestMB: number, explicit?: number): number;
+/**
+ * Re-arm the whole-heap scan guardrail for the work about to be done.
+ *
+ * Scaling a tool's own `timeout_ms` is NOT enough on its own, which is only
+ * obvious once you run against a big graph. The guardrail in `guardrail.ts`
+ * arms a 90s scan budget from the tool's incoming params before the handler
+ * runs; a tool that then computes a larger per-snapshot timeout is still inside
+ * that 90s budget, so a full-heap walk dies at 90s no matter what it asked for.
+ * Measured on a real 690 MB / 5.1M-node Ads Manager capture: a detached-node
+ * probe raised its eval timeout to 414s and still lost the rung to
+ * `Scan exceeded its 90000ms budget`.
+ *
+ * Re-arming per snapshot is what `memlab_analyze_run` already does for its
+ * steps. The guardrail's own `finally` disarms afterwards, so nothing leaks.
+ */
+export declare function armScanBudgetFor(timeoutMs: number): void;
+//# sourceMappingURL=snapshot-borrow.d.ts.map

package/dist/snapshot-borrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-borrow.d.ts","sourceRoot":"","sources":["../src/snapshot-borrow.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAkBhD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CA+BZ;AAED,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,GACrB;IAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAoB5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAExD"}

package/dist/snapshot-borrow.js

@@ -0,0 +1,113 @@
+/**
+ * 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 fs from 'fs';
+import memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { findResidentByPath, getCurrentHandle, getSnapshotByHandle, removeSnapshot, setCurrentSnapshot, setSnapshot, } from './heap-state.js';
+import { beginAnalysisBudget } from './analysis-budget.js';
+import { resolveMaxFileSizeMB, resolveSnapshotPath, } from './tools/load-snapshot.js';
+/**
+ * Run `fn` against the snapshot at `localPath`, loading it only if it is not
+ * already resident, and leaving the session exactly as it was found.
+ *
+ * Every tool that walks an ORDERED ladder needs this, and each one getting it
+ * subtly wrong is the failure mode worth designing out. Three invariants:
+ *
+ *  - **Reuse a resident graph.** Re-parsing a 250 MB capture that is already in
+ *    memory is the single most expensive avoidable thing these tools do.
+ *  - **Hold one graph at a time.** `memlab_eval_across` needs every rung
+ *    resident simultaneously, which is precisely why it cannot serve a ladder of
+ *    large captures. Loading and dropping keeps peak RSS at one rung.
+ *  - **Restore the caller's active snapshot.** A ladder walk is a measurement,
+ *    not a navigation; silently leaving the session pointed at rung 6 makes the
+ *    caller's next `memlab_eval` answer a question about the wrong capture, and
+ *    nothing in that output says so.
+ */
+export async function withSnapshotAt(localPath, fn) {
+    const resident = findResidentByPath(localPath);
+    let snapshot = resident != null ? getSnapshotByHandle(resident.handle) : null;
+    const previousHandle = getCurrentHandle();
+    let temporaryHandle = null;
+    try {
+        if (snapshot == null) {
+            snapshot = await getFullHeapFromFile(localPath);
+            const meta = setSnapshot(snapshot, localPath, {
+                fileName: localPath.replace(/^.*\//, ''),
+                nodeCount: snapshot.nodes?.length ?? 0,
+                edgeCount: snapshot.edges?.length ?? 0,
+                totalSize: 0,
+                env: 'unknown',
+            }, { replace: false });
+            temporaryHandle = meta.handle;
+        }
+        else if (resident != null) {
+            setCurrentSnapshot(resident.handle);
+        }
+        return await fn(snapshot);
+    }
+    finally {
+        if (temporaryHandle != null)
+            removeSnapshot(temporaryHandle);
+        if (previousHandle != null)
+            setCurrentSnapshot(previousHandle);
+    }
+}
+/**
+ * Resolve every path and check its size BEFORE anything is loaded.
+ *
+ * Ordering matters here: an unreadable or oversized rung five should fail in a
+ * second, not after four multi-minute loads have already been paid for.
+ */
+export function resolveRungs(paths, maxFileSizeMB) {
+    const rungs = [];
+    let largestMB = 0;
+    for (const p of paths) {
+        const { localPath, fetchedFrom } = resolveSnapshotPath(p);
+        if (!fs.existsSync(localPath)) {
+            throw new Error(`File not found: ${localPath}`);
+        }
+        const sizeMB = fs.statSync(localPath).size / (1024 * 1024);
+        largestMB = Math.max(largestMB, sizeMB);
+        const limit = resolveMaxFileSizeMB(maxFileSizeMB, fetchedFrom != null);
+        if (sizeMB > limit) {
+            throw new Error(`${p} is ${sizeMB.toFixed(0)} MB — exceeds the ${limit} MB per-file ` +
+                'limit. Raise it with max_file_size_mb.');
+        }
+        rungs.push({ label: p.replace(/^.*\//, ''), localPath, sizeMB });
+    }
+    return { rungs, largestMB };
+}
+/**
+ * A full-heap walk on a multi-million-node graph does not finish inside the
+ * 60 s eval default, and every caller discovering that by timing out first is
+ * pure friction. Scale from the largest rung.
+ */
+export function scaledTimeoutMs(largestMB, explicit) {
+    return explicit ?? Math.max(60000, Math.ceil(largestMB * 600));
+}
+/**
+ * Re-arm the whole-heap scan guardrail for the work about to be done.
+ *
+ * Scaling a tool's own `timeout_ms` is NOT enough on its own, which is only
+ * obvious once you run against a big graph. The guardrail in `guardrail.ts`
+ * arms a 90s scan budget from the tool's incoming params before the handler
+ * runs; a tool that then computes a larger per-snapshot timeout is still inside
+ * that 90s budget, so a full-heap walk dies at 90s no matter what it asked for.
+ * Measured on a real 690 MB / 5.1M-node Ads Manager capture: a detached-node
+ * probe raised its eval timeout to 414s and still lost the rung to
+ * `Scan exceeded its 90000ms budget`.
+ *
+ * Re-arming per snapshot is what `memlab_analyze_run` already does for its
+ * steps. The guardrail's own `finally` disarms afterwards, so nothing leaks.
+ */
+export function armScanBudgetFor(timeoutMs) {
+    beginAnalysisBudget(timeoutMs);
+}
+//# sourceMappingURL=snapshot-borrow.js.map

package/dist/snapshot-borrow.js.map

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

package/dist/string-index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { IHeapNode, IHeapSnapshot } from '@memlab/core';
+/**
+ * Per-value string duplication stats: how many copies, what they cost, and a
+ * bounded sample of node ids to follow up on.
+ */
+export interface StringDupStats {
+    count: number;
+    totalSize: number;
+    exampleIds: number[];
+    /**
+     * Copies reachable ONLY through a dev/automation root. -1 when the index was
+     * built without the dev-root pass (see {@link buildStringIndex}).
+     */
+    devOnlyCount: number;
+}
+export interface StringIndex {
+    byValue: Map<string, StringDupStats>;
+    /** True when `devOnlyCount` is populated. */
+    hasDevOnly: boolean;
+    concatStringCount: number;
+    concatStringSize: number;
+}
+/**
+ * Build (or reuse) the per-value string duplication index for a snapshot.
+ *
+ * `memlab_duplicated_strings` and `memlab_intern_opportunities` were each doing
+ * their own full pass over every string node to build the same value → {count,
+ * size, ids} map, and both are commonly run back to back on the same snapshot —
+ * so the second one re-walked millions of nodes to recompute what the first had
+ * already produced. The scan is cached in the per-snapshot eval scratch, which
+ * already has exactly the lifecycle this needs: keyed by the active handle, and
+ * dropped when that snapshot is replaced or unloaded, so a stale index can never
+ * outlive the graph its node ids refer to.
+ *
+ * `withDevOnly` gates the dev/automation reachability pass, which is a whole-
+ * graph walk that only `intern_opportunities` needs. A cached index built
+ * without it is UPGRADED (rebuilt once) rather than silently returned, since
+ * `devOnlyCount: -1` would otherwise be read as "no dev-only copies".
+ */
+export declare function buildStringIndex(snapshot: IHeapSnapshot, opts?: {
+    withDevOnly?: boolean;
+    isDevOnlyNode?: (node: IHeapNode) => boolean;
+}): StringIndex;
+/** True when this snapshot's string index is already built and resident. */
+export declare function stringIndexIsCached(): boolean;
+//# sourceMappingURL=string-index.d.ts.map

package/dist/string-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-index.d.ts","sourceRoot":"","sources":["../src/string-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAG3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;CACzC,GACL,WAAW,CA8Db;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}