@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/artifact-classes.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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
+ */
+/**
+ * Registry of heap classes whose growth is a MEASUREMENT artifact rather than an
+ * application leak.
+ *
+ * Motivation: across a six-round leak hunt, every single class reported at the
+ * top of `sequence_analysis` as "↑ every step (LEAK signal)" belonged to one of
+ * the families below — CDP inspector bookkeeping, V8 JIT warmup, or captured
+ * error stacks. None was ever a leak. An agent that does not already know this
+ * list reads the label and reports a false leak, which is exactly what happened
+ * repeatedly before the families were catalogued.
+ *
+ * These are deliberately matched on CLASS NAME only. Name matching cannot prove
+ * that a given instance is an artifact, so the classification is used to
+ * annotate and down-rank rows — never to hide them outright (callers can always
+ * pass `include_artifacts: true`). Anything that is genuinely ambiguous is left
+ * unclassified on purpose: a false "this is an artifact" is far more damaging
+ * than a false "this might be a leak".
+ */
+export type ArtifactKind = 'warmup' | 'ax' | 'cdp-network' | 'cdp-perf' | 'cdp-console' | 'stack-capture';
+export declare function artifactLabel(kind: ArtifactKind): string;
+export declare function artifactNote(kind: ArtifactKind): string;
+/**
+ * Where a non-production string came from. Both kinds are equally unshippable,
+ * but they call for different follow-up: `harness` means re-run without the
+ * bridge attached to measure the app cleanly, `dev-build` means measure a
+ * production build.
+ */
+export type NonProductionStringKind = 'harness' | 'dev-build';
+/**
+ * Classify a string VALUE as non-production (harness-injected or DEV-build
+ * only), or null when it is app content that really does ship.
+ */
+export declare function classifyNonProductionString(value: string): {
+    kind: NonProductionStringKind;
+    what: string;
+} | null;
+/**
+ * Back-compatible wrapper returning just the description. Prefer
+ * {@link classifyNonProductionString} when the caller can act on the kind.
+ */
+export declare function classifyHarnessString(value: string): string | null;
+/**
+ * React Fast Refresh module-scope registries, by the edge name that binds each
+ * one. These live in the refresh runtime's closure and are reachable only
+ * through compiled-code constant pools, so a retainer-root scan does not find
+ * them and they classify as `production` unless matched by name here. See
+ * `tools/dev-artifacts` for the measured cost of missing them.
+ */
+export declare const REACT_REFRESH_REGISTRY_EDGE_NAMES: ReadonlySet<string>;
+/**
+ * The rarest property of the react-refresh signature record. Callers gate on
+ * this before confirming the full shape, so a scan stays one name compare per
+ * edge on everything else.
+ */
+export declare const REACT_REFRESH_SIGNATURE_GATE_PROP = "getCustomHooks";
+/**
+ * Recognize the per-type signature record react-refresh stores via
+ * `setSignature(type, key, forceReset, getCustomHooks)` — the value side of
+ * `allSignaturesByType`, shaped `{forceReset, ownKey, fullKey, getCustomHooks}`.
+ */
+export declare function isReactRefreshSignatureShape(propNames: Iterable<string>): boolean;
+/**
+ * Recognize the parent object SHAPE of an MCP/devtools tool manifest entry.
+ *
+ * The bridge's tool definitions carry long `.description` strings — one per tool
+ * — and a per-load intern pool would happily "save" them. The shape is
+ * distinctive enough to match directly, and matching the shape (rather than the
+ * description text) keeps app strings that merely have a `description` property
+ * out of it.
+ */
+export declare function isHarnessToolManifestShape(propNames: ReadonlyArray<string>): boolean;
+/**
+ * Classify a class NAME as a known measurement artifact, or null when it is a
+ * genuine leak candidate.
+ */
+export declare function classifyArtifact(name: string): ArtifactKind | null;
+//# sourceMappingURL=artifact-classes.d.ts.map

package/dist/artifact-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-classes.d.ts","sourceRoot":"","sources":["../src/artifact-classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,IAAI,GACJ,aAAa,GACb,UAAU,GACV,aAAa,GACb,eAAe,CAAC;AAwGpB,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,WAAW,CAAC;AAkE9D;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GACZ;IAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAKtD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAElE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,WAAW,CAAC,MAAM,CAWhE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,mBAAmB,CAAC;AASlE;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,OAAO,CAOT;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,GAC/B,OAAO,CAQT;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CASlE"}

package/dist/artifact-classes.js

@@ -0,0 +1,261 @@
+/**
+ * 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
+ */
+/**
+ * V8 internal structures emitted while JIT-compiling and warming up code paths.
+ * Exercising NEW interactions during a hunt compiles new functions, so this
+ * whole family climbs "every step" without being an app leak.
+ *
+ * Note what is deliberately NOT here: `PropertyArray`, `DescriptorArray`,
+ * `(object elements)`, `(object properties)`, `Context`. Those grow with real
+ * application objects and suppressing them would hide genuine leaks.
+ */
+const WARMUP_CLASS_NAMES = new Set([
+    'InstructionStream',
+    'Code',
+    'CodeDataContainer',
+    'CodeWrapper',
+    'BytecodeArray',
+    'BytecodeWrapper',
+    'FeedbackVector',
+    'FeedbackMetadata',
+    'FeedbackCell',
+    'ClosureFeedbackCellArray',
+    'ScopeInfo',
+    'SharedFunctionInfo',
+    'SharedFunctionInfoWrapper',
+    'UncompiledDataWithoutPreparseData',
+    'UncompiledDataWithPreparseData',
+    'InterpreterData',
+    'TrustedByteArray',
+    'ProtectedFixedArray',
+    'TrustedWeakFixedArray',
+    'WeakArrayList',
+    'LoadHandler',
+    'StoreHandler',
+    'AllocationSite',
+    'ConstantPool',
+    '(constant pool)',
+    'ObjectBoilerplateDescription',
+]);
+/**
+ * Blink accessibility caches, materialized by CDP-driven automation.
+ */
+const AX_NAME_RE = /AXObjectCache|AXNodeObject|AXDirtyObject|AXComputedObject|blink::AX/;
+/**
+ * The attached inspector's network log. Every request the page makes while CDP
+ * is attached is retained by `blink::InspectorNetworkAgent` for the lifetime of
+ * the session, so on a dev build that polls (hot reload, long-poll transports)
+ * this climbs forever. Retained by the DevToolsSession, not by the app.
+ */
+const CDP_NETWORK_NAME_RE = /NetworkResourcesData|XHRReplayData|InspectorNetworkAgent|PerformanceResourceTiming|^URI$/;
+/**
+ * The inspector's performance timeline. Long-task/layout-shift/script-timing
+ * entries accumulate only because something is observing them.
+ */
+const CDP_PERF_NAME_RE = /PerformanceLongTaskTiming|PerformanceLongAnimationFrameTiming|PerformanceScriptTiming|TaskAttributionTiming|ScriptTimingInfo|^LayoutShift$|LayoutShiftAttribution/;
+/**
+ * Console message storage held by the inspector. Distinct from
+ * `dev_artifacts`' console detection, which works on retainer edges: this
+ * catches the native message objects by class name.
+ */
+const CDP_CONSOLE_NAME_RE = /ConsoleMessage/;
+/**
+ * Captured error stacks. `StackFrameInfo` / `ErrorStackData` balloon when
+ * something constructs `Error`s at high frequency — most often React's DEV-only
+ * `_debugStack` owner stacks (see the `reactDebugStack` detector in
+ * `dev-artifacts`), or dev-build logging that captures a stack per record.
+ *
+ * Flagged as `stack-capture` rather than asserted dev-only: a production build
+ * can legitimately grow these, so the annotation points at the likely cause
+ * instead of dismissing the row.
+ */
+const STACK_CAPTURE_NAME_RE = /StackFrameInfo|ErrorStackData/;
+const KIND_LABEL = {
+    warmup: '⚙ JIT/compile warmup (not a leak)',
+    ax: '♿ a11y/CDP cache (automation artifact)',
+    'cdp-network': '🔌 CDP network-inspector retention (artifact)',
+    'cdp-perf': '🔌 CDP performance-timeline retention (artifact)',
+    'cdp-console': '🔌 CDP console retention (artifact)',
+    'stack-capture': '🧵 captured Error stacks (often React DEV _debugStack)',
+};
+const KIND_NOTE = {
+    warmup: '⚙️ V8 **compilation-warmup** structures (`Code`, `BytecodeArray`, `FeedbackVector`, `ScopeInfo`, `InstructionStream`, …) are growing. Exercising new code paths during a hunt JIT-compiles them, so they climb every step without being an app leak.',
+    ax: '♿ Blink **accessibility caches** (`AXObjectCacheImpl` / `AXNodeObject` / `AXDirtyObject`) are growing. These are inflated by CDP-driven automation building the a11y tree, and they co-retain detached DOM, so retainer traces can route through them and mislead.',
+    'cdp-network': '🔌 The attached inspector is retaining the **network log** (`blink::NetworkResourcesData` / `XHRReplayData` / `PerformanceResourceTiming`). Every request made while CDP is attached is held by `blink::DevToolsSession → InspectorNetworkAgent` for the session, so a dev build that polls (hot reload, long-poll transports) grows this forever. Not app memory.',
+    'cdp-perf': '🔌 The attached inspector is retaining the **performance timeline** (long-task / layout-shift / script-timing entries). These accumulate because something is observing them, not because the app leaks.',
+    'cdp-console': '🔌 The attached inspector is retaining **console messages**. Cross-check with `memlab_dev_artifacts`, which also detects console retention by retainer edge.',
+    'stack-capture': '🧵 **Captured Error stacks** (`StackFrameInfo` / `ErrorStackData`) are growing. The usual cause is React DEV `_debugStack` owner stacks or dev-build logging that captures a stack per record — both dev-build-only. `memlab_dev_artifacts` reports the `React DEV owner stack` category when that is the source.',
+};
+export function artifactLabel(kind) {
+    return KIND_LABEL[kind];
+}
+export function artifactNote(kind) {
+    return KIND_NOTE[kind];
+}
+/**
+ * Content signatures of strings that do NOT ship: the CDP-driven bridge the
+ * agent injects to observe the page (browser MCP plugin, browser-tools
+ * extension, Puppeteer helpers), and DEV-build-only framework machinery.
+ *
+ * Why this needs its own classifier, separate from `classifyArtifact`: these are
+ * matched on string CONTENT, not on a class name, and they are not reachable
+ * from a dev *global*, so neither the class-name registry above nor
+ * `dev_artifacts`' root scan sees them.
+ *
+ * Why it matters: on a measured WA Web round the injected bridge bundle appeared
+ * as 64 copies of one 235.6 KB string — 14.7 MB total, the single largest entry
+ * in `duplicated_strings` and the single largest "opportunity" in
+ * `intern_opportunities`. Interning it would save the application nothing,
+ * because none of it ships. Reporting it as a win is worse than not reporting it
+ * at all: it sends a fix author after the test rig. The React DEV entries below
+ * were the same story a round later: 4,529 `_debugStack` Error stacks, 3.0 MB,
+ * none of which exist in a production build.
+ *
+ * Every pattern here has to be specific enough that application source cannot
+ * match it — a false "this doesn't ship" hides a real win, which is the more
+ * expensive direction to be wrong in for THIS classifier (the opposite of
+ * `classifyArtifact`, where a false artifact hides a real leak).
+ */
+const NON_PRODUCTION_STRING_SIGNATURES = [
+    {
+        // The UMD/CommonJS prologue every bundled bridge is wrapped in. Anchored at
+        // the start and required to reach `commonjsGlobal` within the prologue, so
+        // ordinary application source strings do not match.
+        re: /^\(function\s*\(exports\)\s*\{[\s\S]{0,400}commonjsGlobal/,
+        kind: 'harness',
+        what: 'injected CommonJS bundle (automation/devtools bridge)',
+    },
+    {
+        re: /^\s*at (?:Object\.)?__PUPPETEER|puppeteer_evaluation_script/,
+        kind: 'harness',
+        what: 'Puppeteer evaluation frame',
+    },
+    {
+        // react-dom DEV names the frames it inserts into owner stacks
+        // `react-stack-top-frame` / `react-stack-bottom-frame`, in hyphenated and
+        // underscored spellings depending on the build. BOTH ends must be matched:
+        // measured on one 2.5M-node capture, `react-stack-top-frame` appears 56
+        // times and `react_stack_bottom_frame` twice, so a bottom-only pattern
+        // misses the dominant form and classifies most DEV owner stacks as
+        // production. The hyphenated spelling cannot be a JS identifier, so it only
+        // ever appears inside a captured stack string.
+        re: /react[-_]stack[-_](?:top|bottom)[-_]frame/,
+        kind: 'dev-build',
+        what: 'React DEV owner stack (_debugStack) — not captured in production',
+    },
+    {
+        // A compiled DEV module's Fast Refresh epilogue. Requires the call form, so
+        // a string that merely mentions the identifier does not match.
+        re: /\$RefreshReg\$\(|\$RefreshSig\$\(/,
+        kind: 'dev-build',
+        what: 'React Fast Refresh instrumentation in compiled source (DEV bundle only)',
+    },
+];
+/**
+ * Classify a string VALUE as non-production (harness-injected or DEV-build
+ * only), or null when it is app content that really does ship.
+ */
+export function classifyNonProductionString(value) {
+    for (const { re, kind, what } of NON_PRODUCTION_STRING_SIGNATURES) {
+        if (re.test(value))
+            return { kind, what };
+    }
+    return null;
+}
+/**
+ * Back-compatible wrapper returning just the description. Prefer
+ * {@link classifyNonProductionString} when the caller can act on the kind.
+ */
+export function classifyHarnessString(value) {
+    return classifyNonProductionString(value)?.what ?? null;
+}
+/**
+ * React Fast Refresh module-scope registries, by the edge name that binds each
+ * one. These live in the refresh runtime's closure and are reachable only
+ * through compiled-code constant pools, so a retainer-root scan does not find
+ * them and they classify as `production` unless matched by name here. See
+ * `tools/dev-artifacts` for the measured cost of missing them.
+ */
+export const REACT_REFRESH_REGISTRY_EDGE_NAMES = new Set([
+    'allFamiliesByID',
+    'allFamiliesByType',
+    'allSignaturesByType',
+    'updatedFamiliesByType',
+    'pendingUpdates',
+    'helpersByRendererID',
+    'helpersByRoot',
+    'mountedRoots',
+    'failedRoots',
+    'rootElements',
+]);
+/**
+ * The rarest property of the react-refresh signature record. Callers gate on
+ * this before confirming the full shape, so a scan stays one name compare per
+ * edge on everything else.
+ */
+export const REACT_REFRESH_SIGNATURE_GATE_PROP = 'getCustomHooks';
+const REACT_REFRESH_SIGNATURE_PROPS = [
+    'forceReset',
+    'ownKey',
+    'fullKey',
+    'getCustomHooks',
+];
+/**
+ * Recognize the per-type signature record react-refresh stores via
+ * `setSignature(type, key, forceReset, getCustomHooks)` — the value side of
+ * `allSignaturesByType`, shaped `{forceReset, ownKey, fullKey, getCustomHooks}`.
+ */
+export function isReactRefreshSignatureShape(propNames) {
+    const seen = new Set();
+    for (const name of propNames) {
+        if (REACT_REFRESH_SIGNATURE_PROPS.includes(name))
+            seen.add(name);
+        if (seen.size === REACT_REFRESH_SIGNATURE_PROPS.length)
+            return true;
+    }
+    return false;
+}
+/**
+ * Recognize the parent object SHAPE of an MCP/devtools tool manifest entry.
+ *
+ * The bridge's tool definitions carry long `.description` strings — one per tool
+ * — and a per-load intern pool would happily "save" them. The shape is
+ * distinctive enough to match directly, and matching the shape (rather than the
+ * description text) keeps app strings that merely have a `description` property
+ * out of it.
+ */
+export function isHarnessToolManifestShape(propNames) {
+    const props = new Set(propNames);
+    return (props.has('description') &&
+        props.has('inputSchema') &&
+        (props.has('call') || props.has('handler')) &&
+        props.has('name'));
+}
+/**
+ * Classify a class NAME as a known measurement artifact, or null when it is a
+ * genuine leak candidate.
+ */
+export function classifyArtifact(name) {
+    const bare = name.replace(/^system \/ /, '');
+    if (WARMUP_CLASS_NAMES.has(bare))
+        return 'warmup';
+    if (AX_NAME_RE.test(name))
+        return 'ax';
+    if (CDP_NETWORK_NAME_RE.test(bare))
+        return 'cdp-network';
+    if (CDP_PERF_NAME_RE.test(bare))
+        return 'cdp-perf';
+    if (CDP_CONSOLE_NAME_RE.test(bare))
+        return 'cdp-console';
+    if (STACK_CAPTURE_NAME_RE.test(bare))
+        return 'stack-capture';
+    return null;
+}
+//# sourceMappingURL=artifact-classes.js.map

package/dist/artifact-classes.js.map

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

package/dist/capture-mode.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 { SnapshotEnv } from './heap-state.js';
+/**
+ * Was this snapshot captured with numeric-value capture on?
+ *
+ * Background: `heap number` is a perennial top grower, and the standing advice
+ * was "that is probably a capture artifact — check whether you captured with
+ * numeric values on". That advice pushed a decision onto the caller that the
+ * caller usually cannot answer (the snapshot may be days old, or captured by
+ * someone else), and it rested on a mechanism that was never measured.
+ *
+ * It was measured for this change, with matched pairs — the same program/page,
+ * two snapshots differing ONLY in the `captureNumericValue` CDP flag:
+ *
+ *  - **Node.js** (`inspector` → `HeapProfiler.takeHeapSnapshot`): the flag adds
+ *    `smi number` nodes and nothing else. Off: 10,100 number nodes, zero of them
+ *    `smi number`. On: 10,390, of which 290 `smi number`. `heap number` was
+ *    IDENTICAL at 10,100 in both. Smis are immediate values, not heap objects,
+ *    so they only become graph nodes when the flag asks V8 to materialize them —
+ *    which makes their presence a sound detector here.
+ *  - **Chrome**: no detectable difference at all. On a page holding 20,000
+ *    objects each with a double and a Smi field, on and off produced the same
+ *    populations to the node: 40,026 `heap number`, 20,000 `smi number`, 1,063
+ *    `int`. Chrome emits `smi number` either way, so the Node detector does not
+ *    transfer, and no other field varies.
+ *
+ * Neither environment ever encodes the numeric VALUE in the node name (0
+ * value-named number nodes across all four snapshots), so name-based detection
+ * — the approach a previous round tried and rejected — cannot work in principle.
+ *
+ * Two consequences, both of which change what the tools should say:
+ *  1. For a BROWSER snapshot the question is not merely unanswerable, it is
+ *     moot: the flag changes nothing, so `heap number` growth in a browser
+ *     capture is never a numeric-capture artifact and must be investigated as
+ *     real.
+ *  2. The old claim that the mode "emits one node per distinct number and ~3x
+ *     inflates the graph" is not what was measured in either environment.
+ */
+export type NumericCaptureMode = 'on' | 'off' | 'not-applicable' | 'unknown';
+export interface NumericCaptureVerdict {
+    mode: NumericCaptureMode;
+    /** One sentence stating the answer, for direct inclusion in a tool result. */
+    note: string;
+}
+/**
+ * @param env  which runtime produced the snapshot
+ * @param hasSmiNumberNodes whether any `smi number` node is present
+ */
+export declare function classifyNumericCapture(env: SnapshotEnv, hasSmiNumberNodes: boolean): NumericCaptureVerdict;
+/** Class-histogram key for the marker node type, as `type::name`. */
+export declare const SMI_NUMBER_CLASS_KEY = "number::smi number";
+//# sourceMappingURL=capture-mode.d.ts.map

package/dist/capture-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-mode.d.ts","sourceRoot":"","sources":["../src/capture-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,KAAK,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,kBAAkB,CAAC;IACzB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,WAAW,EAChB,iBAAiB,EAAE,OAAO,GACzB,qBAAqB,CAsBvB;AAED,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,uBAAuB,CAAC"}

package/dist/capture-mode.js

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+/**
+ * @param env  which runtime produced the snapshot
+ * @param hasSmiNumberNodes whether any `smi number` node is present
+ */
+export function classifyNumericCapture(env, hasSmiNumberNodes) {
+    if (env === 'browser') {
+        return {
+            mode: 'not-applicable',
+            note: 'This is a **browser** capture, where `capture_numeric_value` makes no difference to the snapshot: a matched pair taken with the flag on and off produced identical number-node populations (40,026 `heap number` / 20,000 `smi number` in both). So `heap number` growth here is **not** a numeric-capture artifact — treat it as real and trace it with `memlab_retainer_summary` on `heap number`.',
+        };
+    }
+    if (env === 'node') {
+        return hasSmiNumberNodes
+            ? {
+                mode: 'on',
+                note: 'This **Node.js** capture was taken with **numeric-value capture ON** — `smi number` nodes are present, and V8 only materializes Smis as graph nodes in that mode. `smi number` growth is therefore a capture artifact. `heap number` is emitted either way (a matched pair had an identical `heap number` count with the flag on and off), so `heap number` growth is still worth investigating.',
+            }
+            : {
+                mode: 'off',
+                note: 'This **Node.js** capture was taken with **numeric-value capture OFF** (no `smi number` nodes present). `heap number` nodes are therefore ordinary boxed doubles that V8 allocates anyway — this growth may be real, so investigate it rather than dismissing it.',
+            };
+    }
+    return {
+        mode: 'unknown',
+        note: 'The runtime that produced this snapshot could not be identified, so the numeric-capture mode cannot be stated. In browser captures the flag makes no difference; in Node.js captures it adds `smi number` nodes.',
+    };
+}
+/** Class-histogram key for the marker node type, as `type::name`. */
+export const SMI_NUMBER_CLASS_KEY = 'number::smi number';
+//# sourceMappingURL=capture-mode.js.map

package/dist/capture-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-mode.js","sourceRoot":"","sources":["../src/capture-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgDH;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAgB,EAChB,iBAA0B;IAE1B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,gBAAgB;YACtB,IAAI,EAAE,sYAAsY;SAC7Y,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACnB,OAAO,iBAAiB;YACtB,CAAC,CAAC;gBACE,IAAI,EAAE,IAAI;gBACV,IAAI,EAAE,kYAAkY;aACzY;YACH,CAAC,CAAC;gBACE,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,kQAAkQ;aACzQ,CAAC;IACR,CAAC;IACD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,kNAAkN;KACzN,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC"}

package/dist/eval-hints.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ */
+/**
+ * Recognise an eval that is re-implementing a tool that already exists, and say
+ * so alongside the result.
+ *
+ * The discoverability problem this addresses is measured, not hypothetical: in
+ * one long session `memlab_eval_across`, `memlab_population_diff`,
+ * `memlab_event_registry`, `memlab_collection_trend` and `memlab_verify_fix`
+ * all existed, all would have saved work, and none was called — while the same
+ * questions were answered with hand-written evals, several times each. The
+ * operator had even read the warning about exactly this and still did not open
+ * the catalogue, because under time pressure writing the eval is the shorter
+ * path and nothing in that path mentions the alternative.
+ *
+ * So the hint is attached to the RESULT of the call that made the mistake,
+ * which is the one moment the caller is guaranteed to read. Two rules keep it
+ * from becoming noise:
+ *
+ *  - **Never suppress or alter the result.** The eval ran; the hint is a
+ *    footnote. A hint that blocked or replaced output would be worse than the
+ *    duplication it is trying to prevent.
+ *  - **Match on structure, not vocabulary.** A pattern fires only when the code
+ *    shows the SHAPE of the built-in's job (a `{callback, context}` census, a
+ *    per-class count keyed by snapshot, a detached-node distribution), not
+ *    merely because it mentions a word.
+ */
+export interface EvalHint {
+    tool: string;
+    why: string;
+}
+export declare function hintsForEval(code: string): EvalHint[];
+export declare function formatEvalHints(hints: EvalHint[]): string | null;
+//# sourceMappingURL=eval-hints.d.ts.map

package/dist/eval-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-hints.d.ts","sourceRoot":"","sources":["../src/eval-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAkGD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CASrD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,GAAG,IAAI,CAKhE"}

package/dist/eval-hints.js

@@ -0,0 +1,115 @@
+/**
+ * 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 RULES = [
+    {
+        tool: 'memlab_event_registry',
+        why: 'counts `{callback, context}` listener records by event and host directly',
+        // `callback` and `context` are two of the most common identifiers in
+        // JavaScript, so matching them alone fires on evals that have nothing to do
+        // with listeners. Require the SHAPE as well: both read as properties off
+        // the same record, and the eval is accumulating or iterating over them.
+        all: [
+            /[.[]['"]?callback\b|\bcallback\s*:/,
+            /[.[]['"]?context\b|\bcontext\s*:/,
+            /&&|\+\+|\+= ?1|\|\| ?0\) ?\+ ?1|\?\? ?0\) ?\+ ?1|\.push\(|\bfor\b/,
+        ],
+        // Already going through the census tool, or bucketing something else.
+        none: [/memlab_event_registry/],
+    },
+    {
+        tool: 'memlab_detached_dom',
+        why: 'reports the detached-node population and its per-class distribution, using the same pinned/GC-eligible split the other tools use',
+        all: [/is_detached|isRealDetached|Detached </],
+        none: [/memlab_detached_dom/],
+    },
+    {
+        tool: 'memlab_census_diff',
+        why: 'takes the detached and listener census on BOTH rungs and diffs them per class in one call — no manual map-building or unload/reload cycle',
+        all: [
+            /is_detached|isRealDetached|Detached </,
+            /\bbaseline\b|\bbefore\b|\bprev\b/,
+        ],
+        none: [/memlab_census_diff/],
+    },
+    {
+        tool: 'memlab_class_histogram',
+        why: 'produces the per-class count/size table without a hand-written walk',
+        // Deliberately not keyed to the identifier `node`: the callback parameter
+        // is as often `n`, and requiring the long spelling made the rule silently
+        // never fire on the shape it exists to catch.
+        all: [
+            /snapshot\.nodes\.forEach|for\s*\(\s*const\s+\w+\s+of\s+snapshot\.nodes/,
+            /\.name\b/,
+            /\+\+|\+= ?1|\|\| ?0\) ?\+ ?1|\?\? ?0\) ?\+ ?1/,
+        ],
+        none: [/memlab_class_histogram|helpers\.classCounts/],
+    },
+    {
+        tool: 'memlab_ladder_probe',
+        why: 'runs ONE numeric probe across an ordered ladder and returns the series, the per-cycle rate and r² — loading one rung at a time, so it works on captures too large to hold simultaneously',
+        all: [/helpers\.(save|load)\(|__rung|perRung|per_rung/],
+        none: [/memlab_ladder_probe/],
+    },
+    {
+        tool: 'memlab_duplicate_objects',
+        why: 'is a ready-made dedup report over object content signatures',
+        all: [/shapeSignature|objectContentSignature/, /\bMap\b|\bSet\b/],
+        none: [/memlab_duplicate_objects/],
+    },
+    {
+        // One canonical tool name per hint. The pair used to be crammed into this
+        // single field, which rendered as one backticked identifier containing a
+        // slash and spaces — not a name any caller or renderer can resolve. The
+        // sibling tool goes in `why`, as prose, where it belongs.
+        tool: 'memlab_map_entries',
+        why: 'enumerates collection entries without the backing-store walk (see `memlab_weakmap_entries` for WeakMaps)',
+        all: [/table|backing/i, /\bMap\b|\bWeakMap\b/],
+        none: [
+            /helpers\.mapEntries|helpers\.weakmapEntries/,
+            /memlab_map_entries|memlab_weakmap_entries/,
+        ],
+    },
+    {
+        tool: 'memlab_retainer_trace',
+        why: 'walks retainer paths with framework filtering and path collapsing already applied',
+        all: [
+            /\.referrers\b/,
+            /while\s*\(|for\s*\(/,
+            /pathEdge|dominatorNode|\.referrers\[0\]/,
+        ],
+        none: [/memlab_retainer_trace|helpers\.pathBetween/],
+    },
+];
+/**
+ * At most this many hints per call. Beyond two the footnote stops being a
+ * pointer and starts being a second result the caller has to read.
+ */
+const MAX_HINTS = 2;
+export function hintsForEval(code) {
+    const hints = [];
+    for (const rule of RULES) {
+        if (hints.length >= MAX_HINTS)
+            break;
+        if (rule.none?.some(re => re.test(code)))
+            continue;
+        if (!rule.all.every(re => re.test(code)))
+            continue;
+        hints.push({ tool: rule.tool, why: rule.why });
+    }
+    return hints;
+}
+export function formatEvalHints(hints) {
+    if (hints.length === 0)
+        return null;
+    return hints
+        .map(h => `note: \`${h.tool}\` does this directly — it ${h.why}.`)
+        .join('\n');
+}
+//# sourceMappingURL=eval-hints.js.map

package/dist/eval-hints.js.map

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

package/dist/guardrail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../src/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAYvE;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2ChE"}
+{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../src/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAavE;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwDhE"}