next-leak 0.11.2 → 0.12.0

package/dist/{chunk-YLHE4N5G.js → chunk-7WUE3WOI.js}

@@ -1,11 +1,12 @@
 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 {
   effectiveVerdict
-} from "./chunk-4FYSLLSX.js";
+} from "./chunk-4NKGNMEA.js";
 import {
   assessPeakPressure,
-  describePeakPressure
-} from "./chunk-XHPUAMJG.js";
+  describePeakPressure,
+  retainedAfterLoad
+} from "./chunk-E464SO7G.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
@@ -13,7 +14,10 @@ var VERDICT_COLOR = {
   leak: "#c0392b",
   stable: "#27ae60",
   inconclusive: "#e67e22",
-  saturating: "#2980b9"
+  saturating: "#2980b9",
+  // Its own colour, not the leak red: nothing was retained, and nothing is
+  // green about a process that reached a ceiling it cannot come back from.
+  pressure: "#8e44ad"
 };
 function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
@@ -46,7 +50,7 @@ function ownerCell(attribution) {
   return `${attribution.owner}${source}${packageName}`;
 }
 function peakBlock(route, parameters) {
-  const retained = route.memorySamples.at(-1)?.heapUsed;
+  const retained = retainedAfterLoad(route.memorySamples);
   if (retained === void 0 || route.peaks === void 0) {
     return "";
   }

package/dist/{chunk-XHPUAMJG.js → chunk-E464SO7G.js}

@@ -6,6 +6,12 @@ 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 retainedAfterLoad(memorySamples) {
+  const cycles = memorySamples.slice(1);
+  return cycles.length === 0 ? void 0 : cycles.reduce((lowest, sample) => Math.min(lowest, sample.heapUsed), Infinity);
+}
+var reachesHeapCeiling = (heapUsed, heapLimitBytes) => heapUsed >= heapLimitBytes * HEAP_LIMIT_SHARE;
+var reachesRssCeiling = (rss, retainedHeapBytes) => rss >= RSS_FLOOR_BYTES && rss >= retainedHeapBytes * RSS_OVER_RETAINED;
 function assessPeakPressure(input) {
   const sampled = input.peaks.filter((peak) => peak.polls > 0);
   if (sampled.length === 0) {
@@ -14,7 +20,7 @@ function assessPeakPressure(input) {
   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) {
+  if (reachesHeapCeiling(peakHeap, heapLimitBytes)) {
     return {
       class: "heap",
       peakBytes: peakHeap,
@@ -22,7 +28,7 @@ function assessPeakPressure(input) {
       heapLimitBytes
     };
   }
-  if (peakRss >= RSS_FLOOR_BYTES && peakRss >= input.retainedHeapBytes * RSS_OVER_RETAINED) {
+  if (reachesRssCeiling(peakRss, input.retainedHeapBytes)) {
     return {
       class: "rss",
       peakBytes: peakRss,
@@ -32,6 +38,35 @@ function assessPeakPressure(input) {
   }
   return null;
 }
+var PRESSURE_MIN_SETTLED_CYCLES = 2;
+var reachesCeiling = (peak, pressureClass, input) => pressureClass === "heap" ? reachesHeapCeiling(peak.heapUsed, input.maxOldSpaceMb * MB) : reachesRssCeiling(peak.rss, input.retainedHeapBytes);
+function isSustained(input, pressureClass) {
+  if (!input.peaks.every((peak) => peak.polls > 0)) {
+    return false;
+  }
+  const settled = input.peaks.slice(1);
+  if (settled.length < PRESSURE_MIN_SETTLED_CYCLES) {
+    return false;
+  }
+  return settled.every((peak) => reachesCeiling(peak, pressureClass, input));
+}
+function assessPressureVerdict(input) {
+  if (input.trend.verdict !== "stable" && input.trend.verdict !== "saturating") {
+    return input.trend;
+  }
+  const pressure = assessPeakPressure({
+    peaks: input.peaks,
+    retainedHeapBytes: input.retainedHeapBytes,
+    maxOldSpaceMb: input.maxOldSpaceMb
+  });
+  if (pressure === null) {
+    return input.trend;
+  }
+  if (!isSustained(input, pressure.class)) {
+    return input.trend;
+  }
+  return { ...input.trend, verdict: "pressure" };
+}
 var mb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
 function describePeakPressure(pressure) {
   if (pressure.class === "heap") {
@@ -41,6 +76,8 @@ function describePeakPressure(pressure) {
 }
 
 export {
+  retainedAfterLoad,
   assessPeakPressure,
+  assessPressureVerdict,
   describePeakPressure
 };

package/dist/{chunk-AUUMRTZZ.js → chunk-YPVBX3QA.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 {
   assessPeakPressure,
-  describePeakPressure
-} from "./chunk-XHPUAMJG.js";
+  describePeakPressure,
+  retainedAfterLoad
+} from "./chunk-E464SO7G.js";
 
 // src/issue-report.ts
 import path from "path";
@@ -50,7 +51,7 @@ next-leak audits its own run and reports these limits. They do not overturn the
 
 ` + route.confidence.warnings.map((warning) => `- ${warning.detail}`).join("\n") + `
 `;
-  const retainedHeap = route.memorySamples.at(-1)?.heapUsed;
+  const retainedHeap = retainedAfterLoad(route.memorySamples);
   const pressure = retainedHeap === void 0 || route.peaks === void 0 ? null : assessPeakPressure({
     peaks: route.peaks,
     retainedHeapBytes: retainedHeap,

package/dist/cli.js

@@ -22,11 +22,11 @@ import {
   runSelfCheck,
   unregisterChild,
   validateTarget
-} from "./chunk-QNYUT2XF.js";
+} from "./chunk-5VXBMWDN.js";
 import {
   classifyTrend
-} from "./chunk-4FYSLLSX.js";
-import "./chunk-XHPUAMJG.js";
+} from "./chunk-4NKGNMEA.js";
+import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts

package/dist/confidence.d.ts

@@ -21,6 +21,22 @@ import { type TrendResult, type TrendVerdict } from "./trend.js";
  *   resting size
  */
 export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling" | "warm-up-baseline"
+/**
+ * The load filled a cache the route never had to hold, and the run has no
+ * second experiment that would settle how much of the growth that was.
+ *
+ * A cache filling up and memory going missing both retain and both climb;
+ * only a bounded-key re-measurement tells them apart. On an ISR route that
+ * re-measurement is not available: a bounded key set is served from the
+ * cache, so the run drives revalidation to reach the renderer and lands on a
+ * different path of Next's. Measured on the vercel/next.js#99077
+ * reproduction, `/plain` — the same app with the leak taken out — reported
+ * `leak (+180.39 MB/1000 req)` with a fresh key per request and `stable
+ * (+1.81)` bounded, and the two builds that retain 7x apart came out at
+ * +1809.97 and +1815.05 once driven. The number stands as measured; what
+ * cannot stand is a paste-ready draft built on it.
+ */
+ | "cache-residency"
 /**
  * Repeated measurements of the same route did not agree.
  *
@@ -61,6 +77,11 @@ export type ConfidenceInput = {
     maxOldSpaceMb?: number;
     /** Warm-up requests the run sent before the baseline, for the warm-up check. */
     warmupRequests?: number;
+    /**
+     * Whether this route is served from the ISR cache. Decides whether the
+     * cache-residency remedy exists — see `cacheResidencyWarnings`.
+     */
+    revalidatesFromCache?: boolean;
 };
 /**
  * Cycles a re-measurement uses when a verdict came back `inconclusive` — the

package/dist/control-server.d.ts

@@ -11,6 +11,27 @@ export type HeapSample = {
     rss: number;
     external: number;
     arrayBuffers: number;
+    /**
+     * Identity of the process that produced this sample. Optional in the type so
+     * fixtures stay readable; the wire schema in `control-client.ts` requires it,
+     * so a real sample always carries it.
+     */
+    pid?: number;
+    ppid?: number;
+    argv?: readonly string[];
+    cwd?: string;
+    /**
+     * HTTP requests this process has served since boot, counted by the probe in
+     * `bootstrap.ts`. Recorded as evidence of how much traffic reached the
+     * process behind a reading, not checked anywhere: a clustered server counts
+     * in whichever process took the connection. `undefined` when the probe was
+     * not installed.
+     */
+    servedRequests?: number | undefined;
+};
+/** Where `bootstrap.ts` publishes the served-request count. */
+export declare const requestProbe: typeof globalThis & {
+    __nextLeakServedRequests?: number;
 };
 export type ControlServerOptions = {
     /** Directory where heap snapshots are written. */

package/dist/{html-report-O7ILFOF5.js → html-report-6KGPHCMA.js}

@@ -1,9 +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-YLHE4N5G.js";
-import "./chunk-4FYSLLSX.js";
-import "./chunk-XHPUAMJG.js";
+} from "./chunk-7WUE3WOI.js";
+import "./chunk-4NKGNMEA.js";
+import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderHtmlReport

package/dist/index.js

@@ -41,17 +41,17 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-QNYUT2XF.js";
+} from "./chunk-5VXBMWDN.js";
 import {
   renderHtmlReport
-} from "./chunk-YLHE4N5G.js";
+} from "./chunk-7WUE3WOI.js";
 import {
   classifyTrend
-} from "./chunk-4FYSLLSX.js";
+} from "./chunk-4NKGNMEA.js";
 import {
   renderIssueMarkdown
-} from "./chunk-AUUMRTZZ.js";
-import "./chunk-XHPUAMJG.js";
+} from "./chunk-YPVBX3QA.js";
+import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 export {
   LaunchError,

package/dist/isr.d.ts

@@ -25,6 +25,10 @@ export type RevalidationPlan = {
     kind: "drive";
     headers: Record<string, string>;
 }
+/** ISR, but every request asks for a key the cache has never held. */
+ | {
+    kind: "no-cache-to-drive";
+}
 /** ISR, but the manifest cannot supply what an authentic request needs. */
  | {
     kind: "cannot-drive";
@@ -35,5 +39,17 @@ export type RevalidationPlan = {
  *
  * A header the user set themselves wins untouched: someone driving a bespoke
  * revalidation path knows more about it than the manifest does.
+ *
+ * `requestPath` decides whether driving is needed at all. The header does not
+ * merely bypass the cache: it makes Next serve the request through its
+ * revalidation path instead of its normal one, and a route whose render count
+ * depends on the normal path is then measured somewhere its users never go.
+ * Measured on the vercel/next.js#99077 reproduction: with the header, the
+ * `partialPrefetching: true` and `false` builds both created 1.95 timers per
+ * request and were reported at the same +1970 MB/1000 req; without it they
+ * created 3.80 and 0.99 and separated 5x, matching the issue. So the header is
+ * sent only where it buys something — when the load revisits keys the cache
+ * can already hold. With `{n}` every request carries a key the route has never
+ * served, so there is no cache to bypass and driving only distorts.
  */
-export declare function planRevalidation(manifest: PrerenderManifest | undefined, route: string, userHeaders: Record<string, string> | undefined): RevalidationPlan;
+export declare function planRevalidation(manifest: PrerenderManifest | undefined, route: string, userHeaders: Record<string, string> | undefined, requestPath?: string): RevalidationPlan;

package/dist/{issue-report-FPVOZ6HU.js → issue-report-OALZZLVR.js}

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

package/dist/peak-pressure.d.ts

@@ -1,3 +1,5 @@
+import type { TrendResult } from "./trend.js";
+import type { HeapSample } from "./control-server.js";
 import type { PeakSample } from "./ritual.js";
 /**
  * Which ceiling the process came closest to.
@@ -23,17 +25,80 @@ export type PeakPressureInput = {
     retainedHeapBytes: number;
     maxOldSpaceMb: number;
 };
+/**
+ * What a route retains once it has served traffic: the floor of the post-GC
+ * cycle samples, not the last of them.
+ *
+ * Every sample here follows a forced collection, but "after a forced
+ * collection" is not "after everything collectable was collected" — a sample
+ * can carry memory the collector had not reached yet. Measured on the
+ * vercel/next.js#92287 reproduction, 2026-09-24, one run's cycle samples were
+ * 217.1 / 125.0 / 45.2 / 194.9 MB, and the next run's were 69.3 / 121.2 / 48.4
+ * / 41.0. Taking the last put the figure everything here divides by at 194.9 MB
+ * on one run and 41.0 MB on the other, which by itself decided whether the same
+ * app under the same load was reported at all.
+ *
+ * The floor is the honest reading: what a process comes back down to is what it
+ * holds, and everything above it is memory not yet reclaimed. The baseline is
+ * excluded because it precedes any traffic — a route retains nothing before it
+ * has served anything, and dividing by that would make every route look
+ * disproportionate.
+ */
+export declare function retainedAfterLoad(memorySamples: readonly HeapSample[]): number | undefined;
 /**
  * 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.
+ * On its own this stays outside the verdict, and for the original reason:
+ * `leak`/`stable` are statements about retention after GC, calibrated against
+ * real leaks with no false positives, and a peak is a different axis. A single
+ * high peak is a size, not a direction — an app that reserves 600 MB on its
+ * first cycle and holds that level is doing nothing wrong.
+ *
+ * What the note alone could not carry is the rest of that sentence: 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. `assessPressureVerdict` below is where a run
+ * that reaches the ceiling on every cycle stops being a footnote under a `✔`.
  */
 export declare function assessPeakPressure(input: PeakPressureInput): PeakPressure | null;
+export type PressureVerdictInput = {
+    /** The post-GC verdict, exactly as the classifier produced it. */
+    trend: TrendResult;
+    peaks: readonly PeakSample[];
+    retainedHeapBytes: number;
+    maxOldSpaceMb: number;
+};
+/**
+ * Whether a run that retains nothing is nonetheless heading for the ceiling.
+ *
+ * Every number a verdict is computed from is taken after a forced collection,
+ * and production never runs those. That makes the verdict structurally blind to
+ * a whole class of death: memory a full GC does reclaim, allocated faster than
+ * the runtime reclaims it on its own. Measured on the vercel/next.js#92287
+ * reproduction, 2026-09-23 — the app grew ~1 MB of `arrayBuffers` per request
+ * to over 3 GB and died, and this tool called it `stable` at -9.00 MB/1000
+ * requests, because a forced GC handed all of it back before every sample. That
+ * is the trap next-leak exists to warn other people about.
+ *
+ * Three conditions, and no threshold of its own: the ceiling rules are
+ * `assessPeakPressure`'s, asked of each cycle instead of the highest reading.
+ *
+ * - **The post-GC verdict is `stable` or `saturating`.** `leak` is already the
+ *   worse news and `inconclusive` is an admission that the series did not
+ *   decide — promoting *that* to an accusation would be inventing a finding out
+ *   of a measurement that failed.
+ * - **The peak is far enough from what the route retains to be remarked on** —
+ *   `assessPeakPressure`, thresholds unchanged.
+ * - **Every settled cycle reached that ceiling**, not just the highest one.
+ *   This is the condition that makes the verdict safe. A single high peak is an
+ *   episode and gets only the note; a process that returns to the ceiling every
+ *   time it serves traffic is describing what it does under load, which is the
+ *   thing a container is sized against.
+ *
+ * Returns the trend unchanged when it does not qualify, so `trend.verdict`
+ * stays the raw record everywhere else.
+ */
+export declare function assessPressureVerdict(input: PressureVerdictInput): TrendResult;
 /**
  * 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

package/dist/request-probe.d.ts

@@ -0,0 +1,18 @@
+import type { Server } from "node:net";
+/**
+ * Wraps a module's `createServer` so every server it hands out counts the
+ * requests it serves.
+ *
+ * Its own module rather than a helper inside `bootstrap.ts`, because the
+ * bootstrap is an entry point that runs on import and lands inside the
+ * *measured* process — where no coverage instrumentation reaches it, and where
+ * a mistake is only visible as a run whose numbers came from a process that
+ * served nothing.
+ *
+ * `http.createServer` and `https.createServer` have different signatures, so
+ * there is no shared type to borrow. Only the return value is touched, and the
+ * arguments are forwarded untyped and unchanged.
+ */
+export declare function countServedRequests<T extends {
+    createServer: (...args: never[]) => Server;
+}>(module: T): void;

package/dist/route-config.d.ts

@@ -42,6 +42,29 @@ export declare function boundedMarkerOf(value: string): {
     marker: string;
     bound: number;
 } | null;
+/**
+ * Whether a request path mixes both load markers across its segments.
+ *
+ * A single sample value carrying both is rejected when the config loads, but
+ * two params of the same route can each carry a different one, and the mix has
+ * no coherent meaning: the load phase resolves the bounded marker per request
+ * and leaves `{n}` in the path as a literal, so every request asks for a URL
+ * with `%7Bn%7D` in it. The route is refused rather than measured that way.
+ */
+export declare function mixesMarkers(requestPath: string): boolean;
+/**
+ * A concrete path to ask for on behalf of a request path that still carries
+ * load markers.
+ *
+ * The readiness probe has to ask for what the load will ask for, but expanding
+ * the markers belongs to the load phase. Sent as they are, the probe requests a
+ * literal `/posts/post-%7Bn%7D` — a key no request of the run will ever revisit,
+ * planted in the route's cache before the baseline snapshot is taken.
+ *
+ * `0` is the value the build is most likely to have prerendered already, and it
+ * is one the bounded sequence visits anyway.
+ */
+export declare function probeRequestPath(requestPath: string): string;
 /**
  * Substitutes sample values into a dynamic route template and returns a
  * URL-safe request path (or null when a param has no configured value;

package/dist/runner.d.ts

@@ -108,12 +108,18 @@ export type RouteReport = {
      */
     keyCardinality?: number;
     /**
-     * Seconds of the ISR revalidation period this route was driven through,
-     * when it has one. Absent on routes not served from the ISR cache.
-     * Recorded because a curve measured against a cache and one measured
-     * against a re-render are different experiments.
+     * Seconds of this route's ISR revalidation period. Absent on routes not
+     * served from the ISR cache. Recorded because a curve measured against a
+     * cache and one measured against a re-render are different experiments.
      */
     revalidatedEverySeconds?: number;
+    /**
+     * Whether the load carried the build's own revalidation header. Set apart
+     * from the period because the two answer different questions: the period
+     * says the ISR cache is in play, this says which of Next's two paths
+     * served the requests that produced the curve.
+     */
+    revalidationDriven?: true;
     /** 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/dist/trend.d.ts

@@ -1,4 +1,4 @@
-export type TrendVerdict = "leak" | "stable" | "inconclusive" | "saturating";
+export type TrendVerdict = "leak" | "stable" | "inconclusive" | "saturating" | "pressure";
 export type TrendResult = {
     verdict: TrendVerdict;
     /** Mean retained-heap growth per cycle (bytes) over the analyzed window. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",
@@ -51,9 +51,11 @@
       "esbuild": ">=0.28.1",
       "qs": ">=6.15.2",
       "js-yaml": ">=4.3.1 <5",
-      "fast-uri": ">=3.1.5 <4",
+      "fast-uri": ">=3.1.6 <4",
       "ip-address": ">=10.3.1 <11",
-      "postcss": ">=8.5.23 <9"
+      "postcss": ">=8.5.23 <9",
+      "browserslist": ">=4.28.7",
+      "@puppeteer/browsers": "^3.2.2"
     }
   },
   "devDependencies": {