next-leak 0.2.0 → 0.3.0

package/README.md

@@ -162,6 +162,33 @@ separates them, because each one has a different fix:
 - **`inconclusive`** — sustained sub-threshold growth: measure longer. The CLI prints the exact re-run command (`--routes <those> --cycles 6`).
 - **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design.
 
+## Peak pressure: `stable` is not the same as safe
+
+Every verdict above is about what a route **retains** after idle and a forced
+GC. That is the right question for a leak and the wrong one for an
+`OOMKilled`: a process can climb to gigabytes under load, hand it all back
+when the load stops, and still be killed at its peak. So each load cycle is
+also sampled *without* collecting, and the highest value is reported next to
+the verdict:
+
+```
+✔ /[slug]  stable  (-164.08 MB/1000 req)  heap 261.9 MB → 265.7 MB → 35.4 MB → 36.0 MB
+    ▲ peak pressure: peaked at 3145.7 MB rss under load while retaining 36.0 MB —
+      a container sized on what it retains dies on what it reaches
+```
+
+That is a real measurement of the reproduction in
+[vercel/next.js#92287](https://github.com/vercel/next.js/issues/92287): no
+retention, and 3 GB reached. The note fires when the peak heap comes within
+75% of `--max-old-space`, or when peak RSS is at least 8× the retained heap
+and above 512 MB. It never changes the verdict — retention and peak are
+different questions, and only one of them is a leak. A peak is the highest
+value *sampled* (every 250 ms), so it is a lower bound.
+
+If the measured process dies at the limit instead of merely approaching it,
+the route fails saying exactly that, with the limit in force and how to raise
+it.
+
 ## The tool grades its own measurement
 
 A leak detector is an instrument, and a miscalibrated instrument doesn't fail
@@ -233,6 +260,7 @@ through the build's source maps.
   `--max-old-space`, or every route dies as an OOM that is not the app's
   fault. When a run's heap gets close to the cap, the report says so.
 - Borderline routes can flip between `stable`/`leak` across runs — more cycles resolves this.
+- The **peak-pressure** thresholds are calibrated against one reproduction measured in three regimes plus the bundled fixture, not against the ~40-route validation set the verdicts were tuned on. A peak note never changes a verdict, so the cost of a false one is noise, not a false accusation — but treat the exact thresholds as young.
 - The measured app runs with its real environment: routes that call external services will call them under load. Scope with `--routes` and moderate `--requests` accordingly.
 
 ## Development

package/dist/bootstrap.js

@@ -48,6 +48,10 @@ async function startControlServer(options) {
         respond(200, sampleMemory(gcExposed));
         return;
       }
+      if (url.pathname === "/mem") {
+        respond(200, sampleMemory(typeof g.gc === "function"));
+        return;
+      }
       if (url.pathname === "/snapshot") {
         const name = url.searchParams.get("name");
         if (name === null || name === "") {

package/dist/{chunk-HAKKAIHN.js → chunk-2BQ5KXIJ.js}

@@ -7,6 +7,10 @@ import {
   minGrowthFor,
   warrantsIssueDraft
 } from "./chunk-E5ZKAANQ.js";
+import {
+  assessPeakPressure,
+  describePeakPressure
+} from "./chunk-XHPUAMJG.js";
 import {
   __commonJS,
   __esm,
@@ -92205,6 +92209,12 @@ function explainStartupFailure(stderr) {
   return `stderr:
 ${stderr}`;
 }
+function explainRuntimeFailure(stderr, maxOldSpaceMb) {
+  if (/heap out of memory|Reached heap limit|Ineffective mark-compacts/i.test(stderr)) {
+    return `the measured process ran out of heap and was killed by V8 mid-run (limit in force: --max-old-space-size=${maxOldSpaceMb} MB). That is the measurement: this route does not fit in ${maxOldSpaceMb} MB under this load. Raise it with --max-old-space <mb> to match your deployment, or lower --requests/--connections to measure a lighter regime.`;
+  }
+  return `the measured process exited mid-run. ${explainStartupFailure(stderr)}`;
+}
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function pollUntil(deadline, what, probe, failed) {
   for (; ; ) {
@@ -92307,6 +92317,7 @@ async function launchInstrumented(options) {
       pid: child.pid ?? -1,
       appPort: options.appPort,
       controlPort,
+      explainExit: () => exited ? explainRuntimeFailure(stderrTail, options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB) : null,
       close: async () => {
         if (exited) {
           return;
@@ -92409,7 +92420,19 @@ function findingLines(route) {
   }
   return lines;
 }
-function routeLines(route) {
+function peakPressureLines(route, parameters) {
+  const retained = route.memorySamples.at(-1)?.heapUsed;
+  if (retained === void 0) {
+    return [];
+  }
+  const pressure = assessPeakPressure({
+    peaks: route.peaks,
+    retainedHeapBytes: retained,
+    maxOldSpaceMb: parameters.maxOldSpaceMb
+  });
+  return pressure === null ? [] : [`      \u25B2 peak pressure: ${describePeakPressure(pressure)}`];
+}
+function routeLines(route, parameters) {
   if (route.status === "skipped") {
     return [`  \u2013 ${route.route}  skipped: ${route.reason}`];
   }
@@ -92424,13 +92447,14 @@ function routeLines(route) {
     )})  heap ${curve}`,
     ...confidenceLines(route),
     ...memorySourceLines(route, verdict),
+    ...peakPressureLines(route, parameters),
     ...findingLines(route)
   ];
 }
 function formatReport(report) {
   const lines = [`next-leak \u2014 ${report.appDir}`, ""];
   for (const route of report.routes) {
-    lines.push(...routeLines(route));
+    lines.push(...routeLines(route, report.parameters));
   }
   const { minGrowthPerCycle, loadRequests, cycles, maxOldSpaceMb } = report.parameters;
   lines.push(
@@ -93219,6 +93243,9 @@ async function requestGc(port) {
   }
   return sample;
 }
+async function requestMemory(port) {
+  return sampleSchema.parse(await request(port, "/mem"));
+}
 async function requestSnapshot(port, name) {
   const parsed = snapshotResponseSchema.parse(
     await request(port, `/snapshot?name=${encodeURIComponent(name)}`)
@@ -93312,6 +93339,44 @@ Host: ${target.host}\r
 var MIN_POLLS_TO_JUDGE = 2;
 var SETTLE_POLL_MS = 2e3;
 var SETTLE_TOLERANCE = 0.01;
+var PEAK_POLL_MS = 250;
+function pollPeak(controlPort, phase, deps) {
+  const peak = {
+    phase,
+    heapUsed: 0,
+    external: 0,
+    arrayBuffers: 0,
+    rss: 0,
+    polls: 0
+  };
+  let running = true;
+  const loop = (async () => {
+    while (running) {
+      await deps.sleep(PEAK_POLL_MS);
+      if (!running) {
+        return;
+      }
+      let sample;
+      try {
+        sample = await deps.readMemory(controlPort);
+      } catch {
+        return;
+      }
+      peak.polls += 1;
+      peak.heapUsed = Math.max(peak.heapUsed, sample.heapUsed);
+      peak.external = Math.max(peak.external, sample.external);
+      peak.arrayBuffers = Math.max(peak.arrayBuffers, sample.arrayBuffers);
+      peak.rss = Math.max(peak.rss, sample.rss);
+    }
+  })();
+  return {
+    stop: async () => {
+      running = false;
+      await loop;
+      return peak;
+    }
+  };
+}
 async function waitUntilSettled(controlPort, maxIdleMs, deps) {
   const deadline = Date.now() + maxIdleMs;
   let previous = null;
@@ -93335,14 +93400,16 @@ async function waitUntilSettled(controlPort, maxIdleMs, deps) {
 var defaultDeps = {
   launch: launchInstrumented,
   load: runLoadPhase,
-  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  readMemory: requestMemory
 };
 var RITUAL_DEFAULTS = {
   warmupRequests: 200,
   loadRequests: 5e3,
   connections: 100,
   cycles: 4,
-  idleMs: 3e4
+  idleMs: 3e4,
+  maxOldSpaceMb: 512
 };
 async function runRitual(options, deps = defaultDeps) {
   const warmupRequests = options.warmupRequests ?? RITUAL_DEFAULTS.warmupRequests;
@@ -93431,9 +93498,17 @@ async function runRitual(options, deps = defaultDeps) {
       () => requestSnapshot(app.controlPort, "baseline")
     );
     const memorySamples = [baseline.sample];
+    const peaks = [];
     let afterSnapshot = "";
     for (let cycle = 1; cycle <= cycles; cycle += 1) {
-      await timed(`cycle ${cycle} load`, () => loadCycle(`cycle ${cycle}`, loadRequests));
+      await timed(`cycle ${cycle} load`, async () => {
+        const poller = pollPeak(app.controlPort, `cycle ${cycle}`, deps);
+        try {
+          await loadCycle(`cycle ${cycle}`, loadRequests);
+        } finally {
+          peaks.push(await poller.stop());
+        }
+      });
       const settle = await timed(
         `cycle ${cycle} settle`,
         () => waitUntilSettled(app.controlPort, idleMs, deps)
@@ -93460,12 +93535,19 @@ async function runRitual(options, deps = defaultDeps) {
       settleOutcomes,
       samples,
       memorySamples,
+      peaks,
       baselineSnapshot: baseline.file,
       afterSnapshot,
       trend: classifyMemoryTrend(samples, externalSamples, { minGrowthPerCycle }),
       requestsPerCycle: loadRequests,
       minGrowthPerCycle
     };
+  } catch (cause) {
+    const death = app.explainExit();
+    if (death !== null) {
+      throw new Error(death);
+    }
+    throw cause;
   } finally {
     await app.close();
   }
@@ -93797,6 +93879,7 @@ async function measureRoute(context, route, requestPath, index) {
     requestPath,
     samples: result.samples,
     memorySamples: result.memorySamples,
+    peaks: result.peaks,
     timings: result.timings,
     loadOutcomes: result.loadOutcomes,
     settleOutcomes: result.settleOutcomes,
@@ -93812,8 +93895,8 @@ async function measureRoute(context, route, requestPath, index) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-2SOTNXDG.js");
-  const { renderIssueMarkdown } = await import("./issue-report-X5JYAVN5.js");
+  const { renderHtmlReport } = await import("./html-report-KQGUDYK5.js");
+  const { renderIssueMarkdown } = await import("./issue-report-HKA26WNV.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
       const file = path6.join(workDir, `ISSUE-${routeSlug(route.route)}.md`);

package/dist/{chunk-SKAPGI62.js → chunk-BUNQT6VK.js}

@@ -2,6 +2,10 @@ import { createRequire as __nextLeakCreateRequire } from 'node:module';import {
 import {
   effectiveVerdict
 } from "./chunk-E5ZKAANQ.js";
+import {
+  assessPeakPressure,
+  describePeakPressure
+} from "./chunk-XHPUAMJG.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
@@ -36,7 +40,26 @@ function ownerCell(attribution) {
   const packageName = attribution.packageName ? ` (${escapeHtml(attribution.packageName)})` : "";
   return `${attribution.owner}${source}${packageName}`;
 }
-function measuredSection(route) {
+function peakBlock(route, parameters) {
+  const retained = route.memorySamples.at(-1)?.heapUsed;
+  if (retained === void 0 || route.peaks === void 0) {
+    return "";
+  }
+  const pressure = assessPeakPressure({
+    peaks: route.peaks,
+    retainedHeapBytes: retained,
+    maxOldSpaceMb: parameters.maxOldSpaceMb
+  });
+  const peakRows = route.peaks.filter((peak) => peak.polls > 0).map(
+    (peak) => `<tr><td>${escapeHtml(peak.phase)}</td><td>${(peak.heapUsed / MB).toFixed(1)} MB</td><td>${(peak.external / MB).toFixed(1)} MB</td><td>${(peak.arrayBuffers / MB).toFixed(1)} MB</td><td>${(peak.rss / MB).toFixed(1)} MB</td></tr>`
+  ).join("");
+  if (peakRows === "") {
+    return "";
+  }
+  const note = pressure === null ? "" : `<p class="warn">Peak pressure: ${escapeHtml(describePeakPressure(pressure))}</p>`;
+  return note + `<table><tr><th>peak during</th><th>heap</th><th>external</th><th>arrayBuffers</th><th>rss</th></tr>${peakRows}</table>`;
+}
+function measuredSection(route, parameters) {
   if (route.status !== "measured") {
     return "";
   }
@@ -51,7 +74,7 @@ function measuredSection(route) {
     const owner = ownerCell(attribution);
     return `<tr><td>${finding.kind}</td><td>${escapeHtml(finding.nodeType)}</td><td>${escapeHtml(finding.name)}</td><td>${(finding.retainedBytes / MB).toFixed(2)} MB</td><td>${owner}</td></tr>`;
   }).join("");
-  return `<section><h2><span class="badge" style="background:${color}">${verdict}</span> <code>${escapeHtml(route.route)}</code></h2>` + heapCurveSvg(route.samples, color) + `<p class="curve">heap ${curve} MB \xB7 ${(route.growthPer1000Requests / MB).toFixed(2)} MB/1000 req</p>` + withdrawn + warnings + (findingRows === "" ? "" : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;
+  return `<section><h2><span class="badge" style="background:${color}">${verdict}</span> <code>${escapeHtml(route.route)}</code></h2>` + heapCurveSvg(route.samples, color) + `<p class="curve">heap ${curve} MB \xB7 ${(route.growthPer1000Requests / MB).toFixed(2)} MB/1000 req</p>` + withdrawn + warnings + peakBlock(route, parameters) + (findingRows === "" ? "" : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;
 }
 function renderHtmlReport(run) {
   const measured = run.routes.filter((route) => route.status === "measured");
@@ -78,7 +101,7 @@ code{background:#f4f4f4;padding:0 4px;border-radius:3px}
     environment.nextVersion ?? "unknown"
   )} \xB7 next-leak ${escapeHtml(environment.nextLeakVersion)}</p>
 <p class="meta">${run.parameters.cycles} cycles \xD7 ${run.parameters.loadRequests} requests \xB7 heap cap ${run.parameters.maxOldSpaceMb} MB \xB7 growth gate ${(run.parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle</p>
-${measured.map(measuredSection).join("\n")}
+${measured.map((route) => measuredSection(route, run.parameters)).join("\n")}
 ${skipped.length === 0 ? "" : `<h2>Skipped</h2><ul>${skipped.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "skipped" ? route.reason : "")}</li>`).join("")}</ul>`}
 ${failed.length === 0 ? "" : `<h2>Failed</h2><ul>${failed.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "failed" ? route.reason : "")}</li>`).join("")}</ul>`}
 <p class="meta">Raw snapshots and run.json live next to this file \u2014 verify in Chrome DevTools \u2192 Memory \u2192 Load.</p>

package/dist/{chunk-MYYPTZJW.js → chunk-WXAFXVWS.js}

@@ -1,4 +1,8 @@
 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 {
+  assessPeakPressure,
+  describePeakPressure
+} from "./chunk-XHPUAMJG.js";
 
 // src/issue-report.ts
 import path from "path";
@@ -41,6 +45,21 @@ function renderIssueMarkdown(route, run) {
 next-leak audits its own run and reports these limits. They do not overturn the verdict above, but they bound how much weight it carries:
 
 ` + route.confidence.warnings.map((warning) => `- ${warning.detail}`).join("\n") + `
+`;
+  const retainedHeap = route.memorySamples.at(-1)?.heapUsed;
+  const pressure = retainedHeap === void 0 || route.peaks === void 0 ? null : assessPeakPressure({
+    peaks: route.peaks,
+    retainedHeapBytes: retainedHeap,
+    maxOldSpaceMb: parameters.maxOldSpaceMb
+  });
+  const peakSection = pressure === null ? "" : `
+### Peak memory under load
+
+Sampled during the load phases, without forcing collection: ${describePeakPressure(pressure)}. Per cycle:
+
+` + route.peaks.filter((peak) => peak.polls > 0).map(
+    (peak) => `- ${peak.phase}: heap ${(peak.heapUsed / MB).toFixed(1)} MB, external ${(peak.external / MB).toFixed(1)} MB, arrayBuffers ${(peak.arrayBuffers / MB).toFixed(1)} MB, rss ${(peak.rss / MB).toFixed(1)} MB`
+  ).join("\n") + `
 `;
   const curve = route.samples.map((sample) => (sample / MB).toFixed(1)).join(" \u2192 ");
   const deltas = route.trend.deltas.map((delta) => `+${(delta / MB).toFixed(2)}`).join(", ");
@@ -89,7 +108,7 @@ ${evidenceRows(route) || "- (no findings above thresholds)"}
 ${signatures === "" ? "" : `
 **Matched known causes:**
 ${signatures}
-`}${caveats}
+`}${peakSection}${caveats}
 ### Verify it yourself
 
 Raw snapshots (Chrome DevTools \u2192 Memory \u2192 Load, compare baseline vs after):

package/dist/chunk-XHPUAMJG.js

@@ -0,0 +1,46 @@
+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);
+
+// src/peak-pressure.ts
+var MB = 1024 * 1024;
+var HEAP_LIMIT_SHARE = 0.75;
+var RSS_OVER_RETAINED = 8;
+var RSS_FLOOR_BYTES = 512 * MB;
+var maxOf = (peaks, read) => peaks.reduce((highest, peak) => Math.max(highest, read(peak)), 0);
+function assessPeakPressure(input) {
+  const sampled = input.peaks.filter((peak) => peak.polls > 0);
+  if (sampled.length === 0) {
+    return null;
+  }
+  const heapLimitBytes = input.maxOldSpaceMb * MB;
+  const peakHeap = maxOf(sampled, (peak) => peak.heapUsed);
+  const peakRss = maxOf(sampled, (peak) => peak.rss);
+  if (peakHeap >= heapLimitBytes * HEAP_LIMIT_SHARE) {
+    return {
+      class: "heap",
+      peakBytes: peakHeap,
+      retainedBytes: input.retainedHeapBytes,
+      heapLimitBytes
+    };
+  }
+  if (peakRss >= RSS_FLOOR_BYTES && peakRss >= input.retainedHeapBytes * RSS_OVER_RETAINED) {
+    return {
+      class: "rss",
+      peakBytes: peakRss,
+      retainedBytes: input.retainedHeapBytes,
+      heapLimitBytes
+    };
+  }
+  return null;
+}
+var mb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
+function describePeakPressure(pressure) {
+  if (pressure.class === "heap") {
+    return `peaked at ${mb(pressure.peakBytes)} heap under load against a ${mb(pressure.heapLimitBytes)} limit (retains ${mb(pressure.retainedBytes)}) \u2014 the run came close to the heap ceiling even though nothing was retained; peaks are the highest value sampled, not a guaranteed maximum`;
+  }
+  return `peaked at ${mb(pressure.peakBytes)} rss under load while retaining ${mb(pressure.retainedBytes)} \u2014 a container sized on what it retains dies on what it reaches; peaks are the highest value sampled, not a guaranteed maximum`;
+}
+
+export {
+  assessPeakPressure,
+  describePeakPressure
+};

package/dist/cli.js

@@ -9,8 +9,9 @@ import {
   killActiveChildren,
   parseCliArgs,
   runMeasurement
-} from "./chunk-HAKKAIHN.js";
+} from "./chunk-2BQ5KXIJ.js";
 import "./chunk-E5ZKAANQ.js";
+import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts

package/dist/control-client.d.ts

@@ -1,6 +1,11 @@
 import type { HeapSample } from "./control-server.js";
 /** Forces GC in the measured process and returns a settled memory sample. */
 export declare function requestGc(port: number): Promise<HeapSample>;
+/**
+ * Reads memory without collecting. Used to poll a process under load, where a
+ * forced GC would change the number being read.
+ */
+export declare function requestMemory(port: number): Promise<HeapSample>;
 /** Forces GC, writes a named heap snapshot, and returns its path and sample. */
 export declare function requestSnapshot(port: number, name: string): Promise<{
     file: string;

package/dist/control-server.d.ts

@@ -26,6 +26,7 @@ export type ControlServer = {
  * Internal control channel booted inside the measured app's process.
  *
  * - `GET /gc` — force GC, respond with a memory sample.
+ * - `GET /mem` — respond with a memory sample WITHOUT collecting.
  * - `GET /snapshot?name=<label>` — force GC, write `<label>.heapsnapshot`
  *   into `snapshotDir`, respond `{ file, sample }` only once fully written.
  */

package/dist/{html-report-2SOTNXDG.js → html-report-KQGUDYK5.js}

@@ -1,8 +1,9 @@
 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-SKAPGI62.js";
+} from "./chunk-BUNQT6VK.js";
 import "./chunk-E5ZKAANQ.js";
+import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderHtmlReport

package/dist/index.js

@@ -39,16 +39,17 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-HAKKAIHN.js";
+} from "./chunk-2BQ5KXIJ.js";
 import {
   renderHtmlReport
-} from "./chunk-SKAPGI62.js";
+} from "./chunk-BUNQT6VK.js";
 import {
   classifyTrend
 } from "./chunk-E5ZKAANQ.js";
 import {
   renderIssueMarkdown
-} from "./chunk-MYYPTZJW.js";
+} from "./chunk-WXAFXVWS.js";
+import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {
   LaunchError,

package/dist/{issue-report-X5JYAVN5.js → issue-report-HKA26WNV.js}

@@ -1,7 +1,8 @@
 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 {
   renderIssueMarkdown
-} from "./chunk-MYYPTZJW.js";
+} from "./chunk-WXAFXVWS.js";
+import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderIssueMarkdown

package/dist/launcher.d.ts

@@ -25,6 +25,13 @@ export type LaunchedApp = {
     pid: number;
     appPort: number;
     controlPort: number;
+    /**
+     * Why the measured process is gone, or null while it is alive. Without it
+     * 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.
+     */
+    explainExit: () => string | null;
     /** SIGTERM, then SIGKILL after a grace period. Resolves when the child exited. */
     close: () => Promise<void>;
 };
@@ -40,6 +47,13 @@ export declare function killActiveChildren(): void;
  * the messenger, and should say so instead of printing 20 lines of trace.
  */
 export declare function explainStartupFailure(stderr: string): string;
+/**
+ * Same idea as `explainStartupFailure`, for a process that died *during* a
+ * run. Heap exhaustion is the one death this tool can name outright, and it
+ * is a finding rather than an accident: the app did not fit in the limit the
+ * run gave it.
+ */
+export declare function explainRuntimeFailure(stderr: string, maxOldSpaceMb: number): string;
 /**
  * Spawns the measured server in a fresh child process with GC exposed and the
  * control-channel bootstrap preloaded, and waits until both the app port and

package/dist/peak-pressure.d.ts

@@ -0,0 +1,42 @@
+import type { PeakSample } from "./ritual.js";
+/**
+ * Which ceiling the process came closest to.
+ *
+ * `heap` is the only class bounded by `--max-old-space`; `rss` is what a
+ * container kills. `external`/`arrayBuffers` live in rss, which is why they
+ * are reported through it instead of against a limit that does not apply to
+ * them (vercel/next.js#92287: a healthy heap next to 4.3 GB of arrayBuffers).
+ */
+export type PeakPressureClass = "heap" | "rss";
+export type PeakPressure = {
+    class: PeakPressureClass;
+    /** Highest value observed for that class, across cycles (bytes). */
+    peakBytes: number;
+    /** Retained heap the verdict was computed on (bytes). */
+    retainedBytes: number;
+    /** Heap limit in force, in bytes. */
+    heapLimitBytes: number;
+};
+export type PeakPressureInput = {
+    peaks: readonly PeakSample[];
+    /** Post-GC heapUsed of the final sample: what the route actually retains. */
+    retainedHeapBytes: number;
+    maxOldSpaceMb: number;
+};
+/**
+ * Whether a route's peak is far enough from the memory its verdict was
+ * computed on to be worth saying out loud.
+ *
+ * Deliberately outside the verdict: `leak`/`stable`/`inconclusive` are
+ * statements about retention after GC, calibrated against real leaks with no
+ * false positives, and a peak is a different axis. A process that climbs to
+ * 3.5 GB and hands it all back is honestly `stable` — and still OOM-killed in
+ * a 1 GB container.
+ */
+export declare function assessPeakPressure(input: PeakPressureInput): PeakPressure | null;
+/**
+ * One line, phrased so it never contradicts the verdict next to it. A peak is
+ * the highest value *sampled*: a spike shorter than the poll interval is not
+ * observed, so this is a lower bound.
+ */
+export declare function describePeakPressure(pressure: PeakPressure): string;

package/dist/ritual.d.ts

@@ -54,6 +54,24 @@ export type SettleOutcome = {
     /** GC polls taken before converging or giving up. */
     polls: number;
 };
+/**
+ * Highest memory observed *during* a load cycle, per class.
+ *
+ * Every other number in a run is taken after idle and a forced GC, which is
+ * what a verdict about retention needs. It is also blind to the process that
+ * climbs to 3.5 GB under load and hands it all back: `stable`, and dead in a
+ * 1 GB container. A peak is a lower bound — a spike shorter than the poll
+ * interval is never seen.
+ */
+export type PeakSample = {
+    phase: string;
+    heapUsed: number;
+    external: number;
+    arrayBuffers: number;
+    rss: number;
+    /** Readings taken; 0 means the poller never got one. */
+    polls: number;
+};
 export type RitualResult = {
     route: string;
     /** Wall-clock per phase, so slow runs can be explained instead of guessed. */
@@ -66,6 +84,8 @@ export type RitualResult = {
     samples: number[];
     /** Full memory samples in the same order. */
     memorySamples: HeapSample[];
+    /** Highest memory seen during each load cycle, sampled without collecting. */
+    peaks: PeakSample[];
     baselineSnapshot: string;
     afterSnapshot: string;
     trend: TrendResult;
@@ -82,6 +102,8 @@ export type RitualDeps = {
     launch: typeof launchInstrumented;
     load: typeof runLoadPhase;
     sleep: (ms: number) => Promise<void>;
+    /** GC-free read, polled while the app is under load. */
+    readMemory: (port: number) => Promise<HeapSample>;
 };
 /**
  * Single source of truth for ritual defaults — reports must echo them.
@@ -101,6 +123,7 @@ export declare const RITUAL_DEFAULTS: {
     readonly connections: 100;
     readonly cycles: 4;
     readonly idleMs: 30000;
+    readonly maxOldSpaceMb: 512;
 };
 /**
  * Runs the validated phase-0 ritual against one route in a fresh process:

package/dist/runner.d.ts

@@ -4,7 +4,7 @@ import type { HeapSample } from "./control-server.js";
 import { type MeasurementEnvironment } from "./environment.js";
 import { diffSnapshotFiles, type HeapDiff } from "./heap-diff.js";
 import { extractModuleRegistry } from "./module-registry.js";
-import { runRitual, type LoadOutcome, type PhaseTiming, type SettleOutcome } from "./ritual.js";
+import { runRitual, type LoadOutcome, type PeakSample, type PhaseTiming, type SettleOutcome } from "./ritual.js";
 import { readNextVersion, type MatchedSignature } from "./signatures.js";
 import { type TrendResult } from "./trend.js";
 export type RouteReport = {
@@ -28,6 +28,11 @@ export type RouteReport = {
      * different fix than a heap leak.
      */
     memorySamples: HeapSample[];
+    /**
+     * Highest memory reached *during* each load cycle. Every other number
+     * here is post-GC; this is the one a container limit is judged against.
+     */
+    peaks: PeakSample[];
     /** RSS growth per 1000 requests, computed like the heap figure. */
     rssPer1000Requests: number;
     /** Wall-clock per phase — explains where a long run spent its time. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",