next-leak 0.7.0 → 0.9.0

package/dist/cli-args.d.ts

@@ -10,12 +10,15 @@ export type CliRunOptions = {
     quick: boolean;
     noResolve: boolean;
     diffAll: boolean;
+    attributeBuild: boolean;
     writeConfig: boolean;
     output: string | null;
 };
 export type CliBuildOptions = {
     appDir: string;
     output: string | null;
+    /** Opt-in: signal the worker for snapshots and name what it retains. */
+    attributeBuild: boolean;
 };
 export type ParsedCli = {
     kind: "run";

package/dist/cli.js

@@ -2,10 +2,14 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
 import {
   RouteConfigError,
+  SnapshotError,
   TargetError,
+  attributeDiff,
   checkRuntime,
+  diffSnapshotFiles,
   discoverPagesRoutes,
   discoverRoutes,
+  extractModuleRegistry,
   formatReport,
   hasPlaceholders,
   helpText,
@@ -16,7 +20,7 @@ import {
   runMeasurement,
   unregisterChild,
   validateTarget
-} from "./chunk-BXDUPN6Z.js";
+} from "./chunk-UVA77PMC.js";
 import {
   classifyTrend
 } from "./chunk-EJ26OBZI.js";
@@ -25,11 +29,166 @@ import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
 import { spawn as spawn2 } from "child_process";
-import { writeFile } from "fs/promises";
+import { mkdir, writeFile } from "fs/promises";
 import { createRequire } from "module";
-import path3 from "path";
+import path5 from "path";
 import { fileURLToPath } from "url";
 
+// src/build-attribution.ts
+import path2 from "path";
+
+// src/build-snapshot.ts
+import { readdirSync, unlinkSync } from "fs";
+import { readdir, rename, unlink } from "fs/promises";
+import path from "path";
+var PARSEABLE_WORKER_RSS_BYTES = 1024 * 1024 * 1024;
+var START_UP_FLOOR_BYTES = 128 * 1024 * 1024;
+var MIN_PAIR_GROWTH_BYTES = 128 * 1024 * 1024;
+var AFTER_TARGET_RSS_BYTES = Math.floor(PARSEABLE_WORKER_RSS_BYTES * 0.9);
+function decideCapture(rssBytes, stage, baselineRssBytes = null) {
+  if (stage === "pair-taken" || stage === "missed") {
+    return "wait";
+  }
+  if (stage === "waiting") {
+    if (rssBytes > PARSEABLE_WORKER_RSS_BYTES) {
+      return "give-up";
+    }
+    return rssBytes >= START_UP_FLOOR_BYTES ? "take-baseline" : "wait";
+  }
+  const grown = rssBytes - (baselineRssBytes ?? 0);
+  if (rssBytes > PARSEABLE_WORKER_RSS_BYTES) {
+    return "give-up";
+  }
+  if (rssBytes < AFTER_TARGET_RSS_BYTES) {
+    return "wait";
+  }
+  return grown >= MIN_PAIR_GROWTH_BYTES ? "take-after" : "wait";
+}
+var SNAPSHOT_NAME = /^Heap\.\d{8}\.\d{6}\.(\d+)\.\d+\.(\d+)\.heapsnapshot$/;
+var byCodeUnit = (left, right) => {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+};
+function snapshotsWrittenBy(pid, filenames) {
+  return filenames.filter((name) => {
+    const match = SNAPSHOT_NAME.exec(name);
+    return match !== null && Number(match[1]) === pid;
+  }).sort(byCodeUnit);
+}
+async function collectSnapshotPair(appDir, outDir, pid) {
+  let entries;
+  try {
+    entries = await readdir(appDir);
+  } catch {
+    return null;
+  }
+  const written = snapshotsWrittenBy(pid, entries);
+  const [baseline, after] = written;
+  if (baseline === void 0 || after === void 0) {
+    return null;
+  }
+  const baselineFile = path.join(outDir, `worker-${pid}-baseline.heapsnapshot`);
+  const afterFile = path.join(outDir, `worker-${pid}-after.heapsnapshot`);
+  try {
+    await rename(path.join(appDir, baseline), baselineFile);
+    await rename(path.join(appDir, after), afterFile);
+  } catch {
+    await unlink(baselineFile).catch(() => {
+    });
+    await unlink(afterFile).catch(() => {
+    });
+    return null;
+  }
+  return { baselineFile, afterFile };
+}
+async function discardSnapshots(appDir, pid) {
+  let entries;
+  try {
+    entries = await readdir(appDir);
+  } catch {
+    return;
+  }
+  for (const name of snapshotsWrittenBy(pid, entries)) {
+    try {
+      await unlink(path.join(appDir, name));
+    } catch {
+    }
+  }
+}
+function bracketedShare(baselineRssBytes, afterRssBytes, peakRssBytes) {
+  const total = peakRssBytes - baselineRssBytes;
+  if (total <= 0) {
+    return 1;
+  }
+  return Math.min(1, Math.max(0, (afterRssBytes - baselineRssBytes) / total));
+}
+var pendingCapture = null;
+function registerPendingCapture(appDir, pid) {
+  pendingCapture = { appDir, pid };
+}
+function clearPendingCapture() {
+  pendingCapture = null;
+}
+function discardPendingSnapshotsSync() {
+  if (pendingCapture === null) {
+    return;
+  }
+  const { appDir, pid } = pendingCapture;
+  pendingCapture = null;
+  try {
+    for (const name of snapshotsWrittenBy(pid, readdirSync(appDir))) {
+      try {
+        unlinkSync(path.join(appDir, name));
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+
+// src/build-attribution.ts
+var defaultDeps = {
+  diff: diffSnapshotFiles,
+  registry: extractModuleRegistry
+};
+async function attributeBuildCapture(result, appDir, onProgress = () => {
+}, deps = defaultDeps) {
+  const capture = result.capture;
+  if (capture === null) {
+    return null;
+  }
+  onProgress(`diffing what worker ${capture.pid} retained`);
+  let diff;
+  try {
+    diff = await deps.diff(capture.files.baselineFile, capture.files.afterFile);
+  } catch (cause) {
+    onProgress(
+      cause instanceof SnapshotError ? `no attribution: ${cause.message}` : `no attribution: the snapshot pair could not be diffed`
+    );
+    return null;
+  }
+  const registry = await deps.registry(path2.join(appDir, ".next", "server"));
+  return {
+    diff,
+    attributed: attributeDiff(diff, registry),
+    registrySize: registry.size,
+    // Against the captured worker's own peak. `result.peakWorkerRssBytes` is
+    // the highest of every worker, which on a multi-worker build can belong to
+    // a process these findings say nothing about.
+    bracketed: bracketedShare(
+      capture.baselineRssBytes,
+      capture.afterRssBytes,
+      capture.peakRssBytes
+    ),
+    baselineRssBytes: capture.baselineRssBytes,
+    afterRssBytes: capture.afterRssBytes,
+    baselineFile: capture.files.baselineFile,
+    afterFile: capture.files.afterFile
+  };
+}
+
 // src/build-report.ts
 var MB = 1024 * 1024;
 var mb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
@@ -46,7 +205,42 @@ function growthLine(result) {
   const perPage = result.retentionPerPageBytes === null ? "" : `  (${mbPrecise(result.retentionPerPageBytes)}/page over ${result.pagesGenerated} pages)`;
   return `      grew ${mb(result.netGrowthBytes)} across the generation phase${perPage}`;
 }
-function formatBuildReport(result) {
+var MAX_REPORTED_FINDINGS = 3;
+function attributionLines(attribution) {
+  if (attribution === null) {
+    return [];
+  }
+  const { diff, attributed, bracketed } = attribution;
+  const findings = [...diff.grownNodes, ...diff.newNodes];
+  if (findings.length === 0) {
+    return ["", `  nothing grew between the two snapshots`];
+  }
+  const lines = [
+    "",
+    `  what it retained, between ${mb(attribution.baselineRssBytes)} and ${mb(attribution.afterRssBytes)} of worker rss \u2014`,
+    `  ${(bracketed * 100).toFixed(0)}% of the growth this run observed. The rest is not`,
+    `  attributed: a snapshot taken higher up cannot be parsed back.`
+  ];
+  if (attribution.registrySize === 0) {
+    lines.push(
+      `      no module registry resolved, so no owner is named below \u2014 only`,
+      `      where the bytes hang`
+    );
+  }
+  lines.push(
+    `      snapshots: ${attribution.baselineFile} / ${attribution.afterFile}`
+  );
+  for (const [index, finding] of findings.slice(0, MAX_REPORTED_FINDINGS).entries()) {
+    const owner = attributed.findings[index];
+    const name = owner?.source ?? owner?.packageName ?? owner?.owner ?? "unattributed";
+    lines.push(
+      `      \u21B3 ${finding.name === "" ? "(anonymous)" : finding.name} ${mb(finding.retainedBytes)} \xB7 ${name}`,
+      `          ${finding.retainerChain}`
+    );
+  }
+  return lines;
+}
+function formatBuildReport(result, attribution = null) {
   const lines = [`next-leak build \xB7 ${result.appDir}`, ""];
   if (result.strippedCapWarning !== null) {
     lines.push(`  \u25B2 ${result.strippedCapWarning}`, "");
@@ -69,6 +263,21 @@ function formatBuildReport(result) {
     );
     return lines.join("\n");
   }
+  function parentPeakLines(result2) {
+    const peak = result2.parentSamples.reduce(
+      (highest, sample) => Math.max(highest, sample.rssBytes),
+      0
+    );
+    if (peak === 0) {
+      return [];
+    }
+    const last = result2.parentSamples[result2.parentSamples.length - 1];
+    const ended = last === void 0 ? 0 : last.rssBytes;
+    return [
+      `      the build's own process peaked at ${mb(peak)} (ended at ${mb(ended)}) \u2014 reported, not judged:`,
+      `      it sheds while workers climb, so it is never added to the figure above`
+    ];
+  }
   if (result.status === "nothing-to-measure") {
     lines.push(
       `  \u2013 no static-generation worker ran, so there was nothing to measure`,
@@ -101,6 +310,8 @@ function formatBuildReport(result) {
     lines.push(`      ${result.workers.length} workers ran; the verdict is the worst of them`);
   }
   lines.push(
+    ...attributionLines(attribution),
+    ...parentPeakLines(result),
     "",
     `  peak worker rss ${mb(result.peakWorkerRssBytes)} \xB7 sampled from the process tree, so a`,
     `  spike shorter than the polling interval is not observed`
@@ -110,11 +321,11 @@ function formatBuildReport(result) {
 
 // src/build-run.ts
 import { spawn } from "child_process";
-import path2 from "path";
+import path4 from "path";
 
 // src/build-target.ts
-import { access, readFile, readdir } from "fs/promises";
-import path from "path";
+import { access, readFile, readdir as readdir2 } from "fs/promises";
+import path3 from "path";
 var CONFIG_NAMES = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
 async function exists(file) {
   try {
@@ -126,14 +337,14 @@ async function exists(file) {
 }
 async function readPackageJson(appDir) {
   try {
-    return JSON.parse(await readFile(path.join(appDir, "package.json"), "utf8"));
+    return JSON.parse(await readFile(path3.join(appDir, "package.json"), "utf8"));
   } catch {
     return null;
   }
 }
 async function usesWorkerThreads(appDir) {
   for (const name of CONFIG_NAMES) {
-    const file = path.join(appDir, name);
+    const file = path3.join(appDir, name);
     if (!await exists(file)) {
       continue;
     }
@@ -145,10 +356,10 @@ async function usesWorkerThreads(appDir) {
   return false;
 }
 async function validateBuildTarget(appDir) {
-  const resolved = path.resolve(appDir);
+  const resolved = path3.resolve(appDir);
   let entries;
   try {
-    entries = await readdir(resolved);
+    entries = await readdir2(resolved);
   } catch {
     throw new TargetError("NO_BUILD", `Cannot read ${resolved}.`);
   }
@@ -319,15 +530,22 @@ async function sampleProcessTable() {
 // src/build-run.ts
 var POLL_MS = 500;
 function spawnNextBuild(appDir, env) {
-  const nextBin = path2.join(appDir, "node_modules", "next", "dist", "bin", "next");
+  const nextBin = path4.join(appDir, "node_modules", "next", "dist", "bin", "next");
   return spawn(process.execPath, [nextBin, "build"], {
     cwd: appDir,
     env,
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
-var defaultDeps = {
+var signalWorker = (pid) => {
+  try {
+    process.kill(pid, "SIGUSR2");
+  } catch {
+  }
+};
+var defaultDeps2 = {
   spawnBuild: spawnNextBuild,
+  signalWorker,
   sampleTable: sampleProcessTable,
   now: () => Date.now(),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -346,6 +564,22 @@ function recordSample(rows, rootPid, atMs, workers, parentSamples) {
     workers.set(row.pid, series);
   }
 }
+async function collectCapture(options) {
+  const { appDir, workDir, pid, stage, baselineRssBytes, afterRssBytes } = options;
+  if (workDir === void 0 || pid === null) {
+    return null;
+  }
+  if (stage !== "pair-taken" || baselineRssBytes === null || afterRssBytes === null) {
+    await discardSnapshots(appDir, pid);
+    return null;
+  }
+  const files = await collectSnapshotPair(appDir, workDir, pid);
+  if (files === null) {
+    await discardSnapshots(appDir, pid);
+    return null;
+  }
+  return { pid, files, baselineRssBytes, afterRssBytes, peakRssBytes: options.peakRssBytes };
+}
 function worstWorker(workers) {
   let worst = null;
   let worstGrowth = -Infinity;
@@ -359,7 +593,7 @@ function worstWorker(workers) {
   return worst;
 }
 var peakOf = (samples) => samples.reduce((highest, sample) => Math.max(highest, sample.rssBytes), 0);
-async function runBuildMeasurement(options, deps = defaultDeps) {
+async function runBuildMeasurement(options, deps = defaultDeps2) {
   const target = await validateBuildTarget(options.appDir);
   const progress = options.onProgress ?? (() => {
   });
@@ -368,8 +602,13 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   if (strippedCapWarning !== null) {
     progress(strippedCapWarning);
   }
+  const capturing = options.workDir !== void 0;
+  const buildEnv = capturing ? {
+    ...env,
+    NODE_OPTIONS: `${env["NODE_OPTIONS"] ?? ""} --heapsnapshot-signal=SIGUSR2`.trim()
+  } : env;
   progress(`building ${target.appDir}`);
-  const child = deps.spawnBuild(target.appDir, env);
+  const child = deps.spawnBuild(target.appDir, buildEnv);
   registerChild(child);
   let output = "";
   const capture = (chunk) => {
@@ -392,6 +631,36 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   };
   options.signal?.addEventListener("abort", abort, { once: true });
   let samplingFailure = null;
+  let capturePid = null;
+  let captureStage = "waiting";
+  let captureBaselineRss = null;
+  let captureAfterRss = null;
+  const stepCapture = (rows, rootPid) => {
+    const descendants = descendantsOf(rows, rootPid);
+    const followed = capturePid === null ? descendants.find(isStaticGenWorker) : descendants.find((row) => row.pid === capturePid);
+    if (followed === void 0) {
+      return;
+    }
+    capturePid ??= followed.pid;
+    switch (decideCapture(followed.rssBytes, captureStage, captureBaselineRss)) {
+      case "take-baseline":
+        deps.signalWorker(followed.pid);
+        captureStage = "baseline-taken";
+        captureBaselineRss = followed.rssBytes;
+        registerPendingCapture(target.appDir, followed.pid);
+        return;
+      case "take-after":
+        deps.signalWorker(followed.pid);
+        captureStage = "pair-taken";
+        captureAfterRss = followed.rssBytes;
+        return;
+      case "give-up":
+        captureStage = "missed";
+        return;
+      case "wait":
+        return;
+    }
+  };
   const polling = (async () => {
     while (!finished) {
       await deps.sleep(POLL_MS);
@@ -404,6 +673,9 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
         return;
       }
       recordSample(sample.rows, child.pid, deps.now() - startedAt, workerSamples, parentSamples);
+      if (capturing) {
+        stepCapture(sample.rows, child.pid);
+      }
     }
   })();
   const exitCode = await exit;
@@ -412,6 +684,17 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   unregisterChild(child);
   const workers = [...workerSamples].map(([pid, samples]) => ({ pid, samples }));
   const heapExhausted = diedOfHeapExhaustion(output);
+  const capturedSamples = capturePid === null ? void 0 : workerSamples.get(capturePid);
+  const workerCapture = await collectCapture({
+    appDir: target.appDir,
+    workDir: options.workDir,
+    pid: capturePid,
+    stage: captureStage,
+    baselineRssBytes: captureBaselineRss,
+    afterRssBytes: captureAfterRss,
+    peakRssBytes: capturedSamples === void 0 ? 0 : peakOf(capturedSamples)
+  });
+  clearPendingCapture();
   const pagesGenerated = pagesGeneratedFrom(output);
   if (workers.length === 0) {
     return {
@@ -430,6 +713,7 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
       pagesGenerated,
       retentionPerPageBytes: null,
       heapExhausted,
+      capture: workerCapture,
       strippedCapWarning,
       exitCode,
       output
@@ -458,6 +742,9 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
     pagesGenerated,
     retentionPerPageBytes: measured && growthBytes > 0 && pagesGenerated !== null && pagesGenerated > 0 ? growthBytes / pagesGenerated : null,
     heapExhausted,
+    // A pair belonging to a worker other than the one judged supports no claim
+    // about the verdict above, so it is dropped rather than reported next to it.
+    capture: workerCapture !== null && workerCapture.pid === worst?.pid ? workerCapture : null,
     strippedCapWarning,
     exitCode,
     output
@@ -491,6 +778,7 @@ function installInterruptHandlers() {
     process.on(signalName, () => {
       interrupts += 1;
       if (interrupts > 1) {
+        discardPendingSnapshotsSync();
         process.exit(130);
       }
       console.error("\n\xB7 interrupted \u2014 stopping the measured process and writing a partial run.json");
@@ -523,14 +811,31 @@ function handleNonRunCommand(parsed) {
   }
   return false;
 }
-async function runBuildCommand(appDir) {
+async function runBuildCommand(appDir, outputDir, attribute) {
   const aborter = installInterruptHandlers();
+  const workDir = path5.join(
+    outputDir ?? path5.join(appDir, ".next-leak"),
+    (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")
+  );
+  await mkdir(workDir, { recursive: true });
   const result = await runBuildMeasurement({
     appDir,
+    // Capture is opt-in because signalling a worker for a heap snapshot can
+    // stall the build it is measuring. Observed on the #97464 reproduction:
+    // the second signal landed and the worker sat frozen for fourteen minutes
+    // with an empty snapshot file on disk, and on an earlier run for ninety.
+    // A curve and a verdict are what this command promises; naming the objects
+    // is worth asking for, not worth risking every run for.
+    ...attribute && { workDir },
     signal: aborter.signal,
     onProgress: (message) => console.error(`\xB7 ${message}`)
   });
-  console.log(formatBuildReport(result));
+  const attribution = await attributeBuildCapture(
+    result,
+    appDir,
+    (message) => console.error(`\xB7 ${message}`)
+  );
+  console.log(formatBuildReport(result, attribution));
   if (aborter.signal.aborted) {
     process.exitCode = 130;
   }
@@ -543,7 +848,7 @@ async function writeConfigSkeleton(appDir) {
     console.log("no route needs sample params \u2014 nothing to write");
     return;
   }
-  const file = path3.join(target.appDir, "next-leak.config.json");
+  const file = path5.join(target.appDir, "next-leak.config.json");
   try {
     await writeFile(file, `${skeleton}
 `, { flag: "wx" });
@@ -559,6 +864,10 @@ ${skeleton}`
   console.log(`wrote ${file}`);
   if (hasPlaceholders(skeleton)) {
     console.log("replace each REPLACE-ME with a value that exists in your app");
+  } else {
+    console.log(
+      "`{n}` gives every request a different value: a prerendered one serves the warm cache and reads as flat whatever the route retains. Use `{n%200}` to revisit a fixed set of keys, and drop the marker only if the app 404s on params it never prerendered."
+    );
   }
 }
 async function main() {
@@ -567,7 +876,11 @@ async function main() {
     return;
   }
   if (parsed.kind === "build") {
-    await runBuildCommand(parsed.options.appDir);
+    await runBuildCommand(
+      parsed.options.appDir,
+      parsed.options.output,
+      parsed.options.attributeBuild
+    );
     return;
   }
   if (parsed.kind !== "run") {
@@ -606,7 +919,9 @@ async function main() {
     process.exitCode = 130;
     return;
   }
-  if (!report.routes.some((route) => route.status === "measured")) {
+  if (!report.routes.some(
+    (route) => route.status === "measured" || route.status === "died-of-heap"
+  )) {
     console.error("error: no route was measured \u2014 nothing above is a verdict about your app");
     process.exitCode = 1;
   }

package/dist/{html-report-TN7PYVU4.js → html-report-5XMR3EXE.js}

@@ -1,7 +1,7 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
 import {
   renderHtmlReport
-} from "./chunk-RS3AO7HB.js";
+} from "./chunk-T7LM4Z33.js";
 import "./chunk-EJ26OBZI.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";

package/dist/index.js

@@ -39,10 +39,10 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-BXDUPN6Z.js";
+} from "./chunk-UVA77PMC.js";
 import {
   renderHtmlReport
-} from "./chunk-RS3AO7HB.js";
+} from "./chunk-T7LM4Z33.js";
 import {
   classifyTrend
 } from "./chunk-EJ26OBZI.js";

package/dist/launcher.d.ts

@@ -31,11 +31,23 @@ export type LaunchedApp = {
      * a child that died mid-run surfaces as "fetch failed", which reads like a
      * bug in the tool and hides the finding — most often that the app blew
      * through the heap limit the run configured.
+     *
+     * `heapExhausted` separates that one death from every other, because it is
+     * the only one the run is allowed to call a verdict rather than a failure.
      */
-    explainExit: () => string | null;
+    explainExit: () => RuntimeDeath | null;
     /** SIGTERM, then SIGKILL after a grace period. Resolves when the child exited. */
     close: () => Promise<void>;
 };
+/**
+ * How the measured process died. `heapExhausted` is the one death that is a
+ * measurement: the app did not fit in the limit the run gave it, which is the
+ * finding the tool exists to produce. Every other death is a failure.
+ */
+export type RuntimeDeath = {
+    reason: string;
+    heapExhausted: boolean;
+};
 export declare class LaunchError extends Error {
     constructor(message: string);
 }
@@ -61,6 +73,13 @@ export declare function explainStartupFailure(stderr: string): string;
  * is a finding rather than an accident: the app did not fit in the limit the
  * run gave it.
  */
+/**
+ * Whether a stderr window carries V8's own fatal heap message. The build path
+ * asks the same question of build output in `build-verdict.ts`; the two are
+ * deliberately not shared yet, because `launcher` importing the build verdict
+ * would couple the runtime path to it for one regex.
+ */
+export declare function stderrShowsHeapExhaustion(stderr: string): boolean;
 export declare function explainRuntimeFailure(stderr: string, maxOldSpaceMb: number): string;
 /**
  * Spawns the measured server in a fresh child process with GC exposed and the

package/dist/load.d.ts

@@ -24,5 +24,24 @@ export declare class LoadError extends Error {
     readonly result: LoadPhaseResult;
     constructor(message: string, result: LoadPhaseResult);
 }
+/**
+ * Whether the app answers for params it never prerendered.
+ *
+ * A varying sample value is what makes a keyed leak visible, and on an app with
+ * a closed param set (`generateStaticParams` plus `dynamicParams = false`) it is
+ * also what makes every request a 404. The two look identical in the counters —
+ * a wall of non-2xx — and the honest answer is not a guess: request one value
+ * the marker would produce and one the app is known to serve, and compare.
+ *
+ * Measured on an app with `post-0..post-2` prerendered and `dynamicParams` off:
+ * `/post-0` answers 200, `/post-3` answers 404. Without this probe the run told
+ * the user the fault was in their route, and sent them to inspect a route that
+ * was working correctly.
+ *
+ * Note this branch cannot occur under `cacheComponents`: Next rejects
+ * `dynamicParams` at build time when it is enabled, so those apps always render
+ * on demand.
+ */
+export declare function describeUnprerenderedParams(url: string): Promise<string | null>;
 /** Runs one bounded load phase and fails when the error budget is exceeded. */
 export declare function runLoadPhase(options: LoadPhaseOptions): Promise<LoadPhaseResult>;

package/dist/ritual.d.ts

@@ -77,6 +77,30 @@ export type PeakSample = {
     /** Readings taken; 0 means the poller never got one. */
     polls: number;
 };
+/** What survived a process that ran out of heap partway through a run. */
+export type HeapExhaustedEvidence = {
+    /** Post-GC readings taken before the death: baseline first, then per cycle. */
+    memorySamples: HeapSample[];
+    peaks: PeakSample[];
+    unreclaimedSamples: HeapSample[];
+    /** Cycles that finished. Zero means it died inside the first one. */
+    cyclesCompleted: number;
+    cyclesRequested: number;
+    requestsPerCycle: number;
+    baselineSnapshot: string;
+};
+/**
+ * The measured process ran out of heap mid-run.
+ *
+ * Thrown rather than returned because there is no `RitualResult` to build: no
+ * after-snapshot was taken and the trend has nothing complete to classify. It
+ * is still a finding, not a failure — see `explainExit` in `launcher.ts` — and
+ * the evidence it carries is what the report shows instead of a curve.
+ */
+export declare class HeapExhaustedError extends Error {
+    readonly evidence: HeapExhaustedEvidence;
+    constructor(message: string, evidence: HeapExhaustedEvidence);
+}
 export type RitualResult = {
     route: string;
     /** Wall-clock per phase, so slow runs can be explained instead of guessed. */