@memlab/mcp-server 2.18.1 → 2.86.0

package/README.md

@@ -76,21 +76,12 @@ Then configure (`~/.claude.json` for Claude Code, or `.mcp.json` for Cursor/Wind
 
 ## Auto-Approving Tool Permissions
 
-By default, Claude Code prompts you to approve each MCP tool call. To auto-approve all MemLab tools, add this to your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
+By default, Claude Code prompts you to approve each MCP tool call. Every MemLab tool except `memlab_eval` and `memlab_for_each` is strictly read-only heap analysis and safe to auto-approve.
 
-```json
-{
-  "permissions": {
-    "allow": [
-      "mcp__memlab__*"
-    ]
-  }
-}
-```
+> [!CAUTION]
+> **Do not auto-approve `memlab_eval` or `memlab_for_each`.** They execute arbitrary JavaScript with the full privileges of the MCP server process (see the warning under [`memlab_eval`](#memlab_eval)). Leave them on manual approval so each invocation is reviewed. Avoid the `mcp__memlab__*` wildcard, which would auto-approve them too.
 
-The naming convention is `mcp__<server-name>__*` where `memlab` matches the key you used in your MCP server config. The `*` wildcard auto-approves all tools from that server.
-
-You can also allowlist individual tools for granular control, add this to your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
+To auto-approve the read-only tools while keeping the two code-execution tools on manual approval, allowlist the read-only tools explicitly in your `~/.claude/settings.json` (user-level) or `.claude/settings.json` (project-level):
 
 ```json
 {
@@ -105,7 +96,11 @@ You can also allowlist individual tools for granular control, add this to your `
 
 ## How It Works
 
-The server holds a loaded `IHeapSnapshot` in memory across tool calls (loading is expensive for large heaps). Only one snapshot can be loaded at a time. All tools are read-only — they analyze the heap but never modify it.
+The server holds loaded `IHeapSnapshot` graphs in memory across tool calls (loading is
+expensive for large heaps). Several snapshots can be resident at once (`keep_previous: true`);
+tools read the active one, which `memlab_snapshots` switches. When a load's projected working
+set exceeds the free old-space budget, the least-recently-used resident snapshot is evicted
+before the load is refused. All tools are read-only — they analyze the heap but never modify it.
 
 ## Getting a Heap Snapshot
 
@@ -129,11 +124,14 @@ console.log(`Heap snapshot written to ${snapshot}`);
 ### `memlab_load_snapshot`
 
 Load and parse a `.heapsnapshot` file. Builds indexes, computes the dominator tree, and calculates retained sizes. `file_path` may be a local absolute path, a `manifold://bucket/key` URL, or a bare snapshot filename (resolved against the `nest_server_nodejs_heap_snapshots` bucket and fetched via `manifold get`). Pass `keep_previous: true` to keep earlier snapshots resident for diffing/comparison (each gets a handle; manage with `memlab_snapshots`). `quiet` / `suppress_suggestions` set session-wide output controls to trim repeated boilerplate.
+Pass `light: true` for a count-only load that skips the dominator / retained-size /
+shortest-path pass; tools needing retained sizes, dominators or retainer paths then return an
+error naming the light-safe tools instead of reporting zeros.
 
 ```
 Input:  { file_path: "snap.heapsnapshot" | "/abs/path" | "manifold://bucket/key",
           alias?: "before", keep_previous?: false, quiet?: false,
-          suppress_suggestions?: false, max_file_size_mb?: 900 }
+          suppress_suggestions?: false, light?: false, max_file_size_mb?: 900 }
 Output: { status, file_path, node_count, edge_count, total_size, handle }
 ```
 
@@ -157,6 +155,19 @@ Input:  { action?: "list"|"switch"|"unload", handle?: "before",
 Output: resident snapshots (active one marked), or switch/unload result
 ```
 
+### `memlab_batch`
+
+Run several tools against ONE snapshot load and return all their outputs together, instead of
+re-paying the multi-minute parse on every call. Steps run in order against the resident snapshot
+and see each other's side effects. An unknown tool name is rejected before any step runs, and by
+default a failing step is recorded and the batch continues.
+
+```
+Input:  { load?: { ...memlab_load_snapshot args }, steps: [{ tool, args? }],
+          stop_on_error?: false }
+Output: a per-step output block for each step, headed by a run/failed step count
+```
+
 ### `memlab_property_distribution`
 
 For a class/shape and a property, report value cardinality plus the top-K most frequent values. The key tool for diagnosing cardinality explosions (OTel metric attributes, cache keys, per-record fields).
@@ -371,7 +382,10 @@ Input:  { report: "list"|"full_analysis"|"detached_dom"|"duplicated_strings"|...
 
 ### `memlab_eval`
 
-Execute arbitrary JavaScript against the loaded heap snapshot in a sandboxed VM. Has access to `snapshot`, `utils`, and `helpers` but no filesystem/network access.
+Execute arbitrary JavaScript against the loaded heap snapshot. Has access to `snapshot`, `utils`, and `helpers`.
+
+> [!WARNING]
+> **This tool runs arbitrary code with the full privileges of the MCP server process.** It uses `node:vm` to scope the globals it injects, but [`node:vm` is not a security sandbox](https://nodejs.org/api/vm.html) — code can reach the host realm (e.g. `Object.constructor('return process')()`) and from there touch the filesystem, network, and shell. Treat calling `memlab_eval` as equivalent to running code on your machine. The same applies to `memlab_for_each`, whose `filter`/`map`/`reduce` code strings are executed the same way. Do not auto-approve these two tools, and be aware that heap snapshot contents are attacker-influenceable input — a prompt-injection could steer the model into running hostile code here.
 
 ```
 Input:  { code: "...", timeout_ms?: 30000 }

package/bin/.eslintrc.js

@@ -0,0 +1,26 @@
+/**
+ * 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
+ */
+
+// Files in this directory are npm `bin` entry points: package.json declares
+// them as executables, so POSIX requires `#!/usr/bin/env node` on line 1.
+//
+// `fb-www/docblock-first` treats anything preceding the file docblock as
+// disqualifying, and the shebang counts — verified by removing it, at which
+// point the rule stops firing. The two requirements are therefore mutually
+// exclusive for this directory, and the rule's stated rationale (ESLint skips
+// pragma parsing, producing spurious no-undef errors for Flow utility types)
+// does not apply: these are plain CommonJS/ESM Node scripts with no Flow types.
+//
+// Scoped to bin/ so the rule keeps applying to every other file in the package.
+module.exports = {
+  rules: {
+    'fb-www/docblock-first': 'off',
+  },
+};

package/bin/memlab-cli.js

@@ -0,0 +1,313 @@
+/**
+ * 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
+ */
+/// usr/bin/env node
+
+/**
+ * Non-MCP command line for the memlab MCP server.
+ *
+ * Why this exists: the server is only ever reachable through an MCP client, so
+ * when a host fails to attach it (a dropped stdio handshake, a plugin that never
+ * finishes connecting) every tool in the package becomes unavailable at once,
+ * with no diagnostic and no fallback. That happened in practice and cost an
+ * agent ~20 minutes and a hand-written JSON-RPC client before any heap could be
+ * analyzed at all. The server itself was healthy the whole time.
+ *
+ * This speaks the same stdio JSON-RPC the host would, so the tools stay usable
+ * without one:
+ *
+ *   memlab-cli doctor
+ *   memlab-cli list
+ *   memlab-cli schema memlab_load_snapshot
+ *   memlab-cli call memlab_snapshot_header '{"file_path":"/tmp/a.heapsnapshot"}'
+ *   memlab-cli script steps.jsonl        # one {"tool":..,"args":{..}} per line
+ *
+ * `script` (and multiple `call` pairs) reuse ONE server process, which matters:
+ * the server is stateful and a large snapshot costs minutes to load, so a
+ * process per call pays that repeatedly.
+ */
+
+import {spawn} from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+function resolveServerPath() {
+  if (process.env.MEMLAB_MCP_SERVER) {
+    return process.env.MEMLAB_MCP_SERVER;
+  }
+  // Packaged layout is bin/ next to dist/; the plugin copies this script to the
+  // install root, where dist/ is a direct child.
+  const candidates = [
+    path.join(HERE, '..', 'dist', 'index.js'),
+    path.join(HERE, 'dist', 'index.js'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) {
+      return c;
+    }
+  }
+  return candidates[0];
+}
+
+/**
+ * The interpreter to run the SERVER with, which is not necessarily the one
+ * running this CLI: `node` on PATH is frequently older than the package's
+ * `>= 18` engine requirement, and spawning the server with it fails at module
+ * load with an opaque syntax error. Mirrors the plugin start.sh lookup.
+ */
+function resolveNodeBin() {
+  if (Number(process.versions.node.split('.')[0]) >= 18) {
+    return process.execPath;
+  }
+  for (const c of ['/usr/local/bin/claude_code/node']) {
+    if (fs.existsSync(c)) {
+      return c;
+    }
+  }
+  return process.execPath;
+}
+
+class Client {
+  constructor(serverPath) {
+    this.proc = spawn(
+      resolveNodeBin(),
+      ['--max-old-space-size=8192', serverPath],
+      {stdio: ['pipe', 'pipe', 'pipe']},
+    );
+    this.nextId = 0;
+    this.buf = '';
+    this.pending = new Map();
+    this.stderr = [];
+    // Drain stderr. A chatty server that fills this pipe would otherwise block
+    // its own writes and deadlock the session.
+    this.proc.stderr.on('data', d => {
+      this.stderr.push(String(d));
+      if (this.stderr.length > 400) {
+        this.stderr.splice(0, 200);
+      }
+    });
+    this.proc.stdout.on('data', d => this.onData(String(d)));
+    this.proc.on('exit', code => {
+      for (const {reject} of this.pending.values()) {
+        reject(
+          new Error(
+            `memlab server exited (code ${code}). stderr tail:\n${this.stderr.slice(-40).join('')}`,
+          ),
+        );
+      }
+      this.pending.clear();
+    });
+  }
+
+  onData(chunk) {
+    this.buf += chunk;
+    let nl;
+    while ((nl = this.buf.indexOf('\n')) >= 0) {
+      const line = this.buf.slice(0, nl).trim();
+      this.buf = this.buf.slice(nl + 1);
+      if (!line) {
+        continue;
+      }
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const entry = this.pending.get(msg.id);
+      if (!entry) {
+        continue;
+      }
+      this.pending.delete(msg.id);
+      if (msg.error) {
+        entry.reject(new Error(JSON.stringify(msg.error)));
+      } else {
+        entry.resolve(msg.result);
+      }
+    }
+  }
+
+  request(method, params) {
+    const id = ++this.nextId;
+    this.proc.stdin.write(
+      JSON.stringify({jsonrpc: '2.0', id, method, params}) + '\n',
+    );
+    return new Promise((resolve, reject) =>
+      this.pending.set(id, {resolve, reject}),
+    );
+  }
+
+  notify(method, params) {
+    this.proc.stdin.write(
+      JSON.stringify({jsonrpc: '2.0', method, params}) + '\n',
+    );
+  }
+
+  async init() {
+    await this.request('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {name: 'memlab-cli', version: '1.0'},
+    });
+    this.notify('notifications/initialized', {});
+  }
+
+  async listTools() {
+    return (await this.request('tools/list', {})).tools ?? [];
+  }
+
+  async callTool(name, args) {
+    const res = await this.request('tools/call', {name, arguments: args});
+    return (res.content ?? [])
+      .map(c => (c.type === 'text' ? c.text : JSON.stringify(c)))
+      .join('\n');
+  }
+
+  close() {
+    this.proc.stdin.end();
+  }
+}
+
+async function doctor(serverPath) {
+  const major = Number(process.versions.node.split('.')[0]);
+  const nodeBin = resolveNodeBin();
+  const lines = [
+    `cli node: ${process.versions.node}${major >= 18 ? '' : ' (below the >= 18 engine requirement)'}`,
+    `server node: ${nodeBin}${nodeBin === process.execPath && major < 18 ? ' — NO >= 18 interpreter found; the server will fail to load' : ''}`,
+  ];
+  lines.push(`server path: ${serverPath}`);
+  const exists = fs.existsSync(serverPath);
+  lines.push(`server present: ${exists ? 'yes' : 'NO'}`);
+  if (!exists) {
+    lines.push(
+      'Fix: build the package (`npm run build-pkg`), or set MEMLAB_MCP_SERVER to a built dist/index.js.',
+    );
+    console.log(lines.join('\n'));
+    return 1;
+  }
+  // The decisive check: can the server actually start and answer? A corrupted
+  // or partial node_modules only shows up here, not from a file listing.
+  const client = new Client(serverPath);
+  const timer = setTimeout(() => client.proc.kill('SIGKILL'), 60000);
+  try {
+    await client.init();
+    const tools = await client.listTools();
+    lines.push(`handshake: OK`);
+    lines.push(`tools registered: ${tools.length}`);
+    console.log(lines.join('\n'));
+    return 0;
+  } catch (err) {
+    lines.push(`handshake: FAILED — ${err.message}`);
+    lines.push(
+      'Fix: check the install dir for build-errors.log / deps-check-errors.log, ' +
+        'then rebuild (the plugin start.sh does a clean rebuild when dependencies fail to load).',
+    );
+    console.log(lines.join('\n'));
+    return 1;
+  } finally {
+    clearTimeout(timer);
+    client.close();
+  }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const serverPath = resolveServerPath();
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log(
+      [
+        'Usage: memlab-cli <command>',
+        '',
+        '  doctor                      check node, server presence, and a live handshake',
+        '  list                        list tool names and one-line descriptions',
+        '  schema <tool>               print a tool input schema as JSON',
+        '  call <tool> <json> [...]    call one or more tools in ONE server session',
+        '  script <file.jsonl>         run {"tool":..,"args":{..}} lines in ONE session',
+        '',
+        'Server is resolved from $MEMLAB_MCP_SERVER, else dist/index.js next to this script.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+
+  if (cmd === 'doctor') {
+    return doctor(serverPath);
+  }
+
+  const client = new Client(serverPath);
+  try {
+    await client.init();
+    if (cmd === 'list') {
+      for (const t of await client.listTools()) {
+        console.log(`${t.name}\t${(t.description ?? '').slice(0, 150)}`);
+      }
+    } else if (cmd === 'schema') {
+      const want = rest[0];
+      const tool = (await client.listTools()).find(t => t.name === want);
+      if (!tool) {
+        console.error(`Unknown tool: ${want}`);
+        return 1;
+      }
+      console.log(JSON.stringify(tool.inputSchema ?? {}, null, 2));
+    } else if (cmd === 'call') {
+      for (let i = 0; i < rest.length; i += 2) {
+        const tool = rest[i];
+        const args = rest[i + 1] ? JSON.parse(rest[i + 1]) : {};
+        console.log(`\n===== ${tool} =====`);
+        // Sequential by construction: JSON-RPC over ONE stdio socket to a
+        // stateful server (a loaded snapshot). These cannot be parallelised —
+        // the server answers one request at a time and later calls depend on
+        // earlier ones.
+        // eslint-disable-next-line no-await-in-loop
+        console.log(await client.callTool(tool, args));
+      }
+    } else if (cmd === 'script') {
+      const file = rest[0];
+      // Sequential by construction: these are JSON-RPC calls over ONE stdio
+      // socket to a stateful server, so they cannot be parallelised — the next
+      // request depends on the previous one having been answered.
+
+      for (const raw of fs.readFileSync(file, 'utf8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) {
+          continue;
+        }
+        const spec = JSON.parse(line);
+        console.log(`\n===== ${spec.tool} =====`);
+        // Sequential by construction: JSON-RPC over ONE stdio socket to a
+        // stateful server (a loaded snapshot). These cannot be parallelised —
+        // the server answers one request at a time and later calls depend on
+        // earlier ones.
+        // eslint-disable-next-line no-await-in-loop
+        console.log(await client.callTool(spec.tool, spec.args ?? {}));
+      }
+    } else {
+      console.error(`Unknown command: ${cmd}. Try --help.`);
+      return 1;
+    }
+    return 0;
+  } finally {
+    client.close();
+  }
+}
+
+// Terminal by construction: both arms call process.exit, so there is nothing
+// left to chain and no rejection can escape.
+// eslint-disable-next-line fb-www/promise-termination
+main().then(
+  code => process.exit(code ?? 0),
+  err => {
+    console.error(err.message ?? String(err));
+    process.exit(1);
+  },
+);

package/dist/anonymized-snapshot.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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';
+/**
+ * Has this capture had its string content replaced — and if so, in a way that
+ * corrupts the duplication numbers, or not?
+ *
+ * Anonymisers replace string CONTENT while preserving LENGTH. Whether that
+ * matters to an analysis depends entirely on which kind you are looking at, so
+ * this reports three states rather than a boolean:
+ *
+ * - `uniform` — every character replaced by ONE filler character. Every
+ *   distinct string of a given length collapses into the same value, so every
+ *   string-duplication analysis measures the anonymiser instead of the app.
+ *   Measured on one such capture: `memlab_quick_diagnosis` reported **"Total
+ *   interning savings: 47.4 MB"** and `memlab_duplicated_strings` reported a
+ *   single 5.2 KB string duplicated 939 times for 42.1 MB. Both were pure
+ *   artifact. Nothing flagged it; it was caught only because the sample values
+ *   rendered visibly as runs of `?`.
+ * - `stable` — replaced by a value-derived token, so distinctness survives
+ *   along with length. Duplication and interning figures are as true as on the
+ *   original capture, and warning about them would make readers discard
+ *   correct findings. Only the content is unreadable.
+ * - `none` — an ordinary capture.
+ *
+ * Both tests are deliberately cheap and deliberately conservative: sample
+ * strings, and only classify when a large majority match. A normal heap has
+ * plenty of short repeated-character strings ("  ", "----") and plenty of short
+ * lowercase words, so the length floor matters more than the ratio for either.
+ */
+export type AnonymizationKind = 
+/** ordinary capture */
+'none'
+/**
+ * every character replaced by one filler character. Length survives, so
+ * distinct values of equal length collapse into one and duplication figures
+ * become fiction.
+ */
+ | 'uniform'
+/**
+ * replaced by a value-derived token. Length AND distinctness survive, so
+ * duplication figures stay true; only the content is gone.
+ */
+ | 'stable';
+export interface AnonymizationCheck {
+    kind: AnonymizationKind;
+    /**
+     * true only for `uniform`, which is the kind that corrupts duplication
+     * numbers. Existing call sites read this to decide whether to warn, and a
+     * `stable` capture must NOT trip them — its numbers are trustworthy.
+     */
+    anonymized: boolean;
+    sampled: number;
+    singleCharRuns: number;
+    tokenRuns: number;
+    exampleChar?: string;
+}
+export declare function detectAnonymizedStrings(snapshot: IHeapSnapshot): AnonymizationCheck;
+/** The banner every string-content tool prints when the capture is anonymised. */
+export declare function anonymizedStringsBanner(check: AnonymizationCheck): string;
+/**
+ * Prepend the anonymisation banner to a tool's output when it applies.
+ *
+ * Wraps the result rather than being left to each caller to remember, because
+ * "remember to check" is exactly the failure this exists to prevent.
+ */
+export declare function withAnonymizedBanner(snapshot: IHeapSnapshot, text: string): string;
+//# sourceMappingURL=anonymized-snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anonymized-snapshot.d.ts","sourceRoot":"","sources":["../src/anonymized-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB;AAC3B,uBAAuB;AACrB,MAAM;AACR;;;;GAIG;GACD,SAAS;AACX;;;GAGG;GACD,QAAQ,CAAC;AAEb,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,GACtB,kBAAkB,CAqDpB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAwBzE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GACX,MAAM,CAIR"}

package/dist/anonymized-snapshot.js

@@ -0,0 +1,101 @@
+/**
+ * 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 MIN_LEN = 8;
+const SAMPLE_TARGET = 400;
+const RATIO = 0.8;
+export function detectAnonymizedStrings(snapshot) {
+    let sampled = 0;
+    let singleCharRuns = 0;
+    let tokenRuns = 0;
+    let exampleChar;
+    let visited = 0;
+    snapshot.nodes.forEach(node => {
+        if (sampled >= SAMPLE_TARGET)
+            return;
+        if (node.type !== 'string')
+            return;
+        // Stride rather than take the first N: the first strings in a heap are
+        // V8 internals and interned literals, which are never anonymised and would
+        // make every capture look clean.
+        visited++;
+        if (visited % 7 !== 0)
+            return;
+        const value = node.name;
+        if (typeof value !== 'string' || value.length < MIN_LEN)
+            return;
+        sampled++;
+        const first = value[0];
+        let uniform = true;
+        for (let i = 1; i < value.length; i++) {
+            if (value[i] !== first) {
+                uniform = false;
+                break;
+            }
+        }
+        if (uniform) {
+            singleCharRuns++;
+            exampleChar ??= first;
+            return;
+        }
+        // `stable` fill is a run of lowercase letters and nothing else. Real string
+        // values of this length essentially always carry a space, digit, capital or
+        // punctuation mark somewhere, so a heap where most of them are bare
+        // lowercase runs has been rewritten.
+        if (/^[a-z]+$/.test(value)) {
+            tokenRuns++;
+        }
+    });
+    const uniformRatio = sampled >= 20 ? singleCharRuns / sampled : 0;
+    const tokenRatio = sampled >= 20 ? tokenRuns / sampled : 0;
+    const kind = uniformRatio >= RATIO ? 'uniform' : tokenRatio >= RATIO ? 'stable' : 'none';
+    return {
+        kind,
+        anonymized: kind === 'uniform',
+        sampled,
+        singleCharRuns,
+        tokenRuns,
+        exampleChar,
+    };
+}
+/** The banner every string-content tool prints when the capture is anonymised. */
+export function anonymizedStringsBanner(check) {
+    if (check.kind === 'stable') {
+        // Deliberately NOT a warning about the numbers. `stable` anonymization
+        // preserves distinctness, so duplication and interning figures are exactly
+        // as true as on the original capture — saying otherwise here would make
+        // readers discard correct findings.
+        const pct = check.sampled
+            ? Math.round((check.tokenRuns / check.sampled) * 100)
+            : 0;
+        return (`> ℹ️ **This capture is ANONYMISED (value-stable) — ${pct}% of sampled string values are opaque tokens.** ` +
+            'String CONTENT has been replaced, but lengths and distinctness were preserved, so counts, sizes, duplication and interning figures below are accurate. ' +
+            'What you cannot do is read the strings: a sample value tells you nothing about the real data, so identify records by property shape rather than by value.');
+    }
+    const pct = check.sampled
+        ? Math.round((check.singleCharRuns / check.sampled) * 100)
+        : 0;
+    return (`> ⚠️ **This capture looks ANONYMISED — ${pct}% of sampled strings are a single character (\`${check.exampleChar ?? '?'}\`) repeated.** ` +
+        'An anonymiser replaces string content but preserves length, so every distinct string of the same length collapses to the same value. ' +
+        '**Every duplication and interning figure below is manufactured by that collapse and does not exist in the real app.** ' +
+        'Do not quote them, and do not open an interning task from them. Composition, populations, retainer paths and dominator-deduped sizes are unaffected and remain trustworthy.');
+}
+/**
+ * Prepend the anonymisation banner to a tool's output when it applies.
+ *
+ * Wraps the result rather than being left to each caller to remember, because
+ * "remember to check" is exactly the failure this exists to prevent.
+ */
+export function withAnonymizedBanner(snapshot, text) {
+    const check = detectAnonymizedStrings(snapshot);
+    if (check.kind === 'none')
+        return text;
+    return `${anonymizedStringsBanner(check)}\n\n${text}`;
+}
+//# sourceMappingURL=anonymized-snapshot.js.map

package/dist/anonymized-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymized-snapshot.js","sourceRoot":"","sources":["../src/anonymized-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4DH,MAAM,OAAO,GAAG,CAAC,CAAC;AAClB,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,MAAM,KAAK,GAAG,GAAG,CAAC;AAElB,MAAM,UAAU,uBAAuB,CACrC,QAAuB;IAEvB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,WAA+B,CAAC;IACpC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;QAC5B,IAAI,OAAO,IAAI,aAAa;YAAE,OAAO;QACrC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO;QACnC,uEAAuE;QACvE,2EAA2E;QAC3E,iCAAiC;QACjC,OAAO,EAAE,CAAC;QACV,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO;YAAE,OAAO;QAChE,OAAO,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;gBACvB,OAAO,GAAG,KAAK,CAAC;gBAChB,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,cAAc,EAAE,CAAC;YACjB,WAAW,KAAK,KAAK,CAAC;YACtB,OAAO;QACT,CAAC;QACD,4EAA4E;QAC5E,4EAA4E;QAC5E,oEAAoE;QACpE,qCAAqC;QACrC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,SAAS,EAAE,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,UAAU,GAAG,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,IAAI,GACR,YAAY,IAAI,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;IAE9E,OAAO;QACL,IAAI;QACJ,UAAU,EAAE,IAAI,KAAK,SAAS;QAC9B,OAAO;QACP,cAAc;QACd,SAAS;QACT,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,uBAAuB,CAAC,KAAyB;IAC/D,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,uEAAuE;QACvE,2EAA2E;QAC3E,wEAAwE;QACxE,oCAAoC;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO;YACvB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC;YACrD,CAAC,CAAC,CAAC,CAAC;QACN,OAAO,CACL,sDAAsD,GAAG,kDAAkD;YAC3G,yJAAyJ;YACzJ,2JAA2J,CAC5J,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO;QACvB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC;QAC1D,CAAC,CAAC,CAAC,CAAC;IACN,OAAO,CACL,0CAA0C,GAAG,kDAAkD,KAAK,CAAC,WAAW,IAAI,GAAG,kBAAkB;QACzI,uIAAuI;QACvI,wHAAwH;QACxH,6KAA6K,CAC9K,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAuB,EACvB,IAAY;IAEZ,MAAM,KAAK,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;AACxD,CAAC"}