next-leak 0.11.3 → 0.12.0

package/README.md

@@ -241,6 +241,7 @@ separates them, because each one has a different fix:
 | A route that is expensive, not leaky | `failed` under load it cannot sustain, flat once concurrency fits | Real leaks survive forced GC at any concurrency; saturation disappears when load drops |
 | Growth that pauses and resumes (stepwise) | `leak` | A healthy route gives back 20-30% of its growth; a stepwise leak gives back nothing |
 | A cache filling up under the load that measures it | `saturating` | A bounded store grows by less each cycle as new keys get rarer; a leak does not decelerate |
+| Memory a forced GC reclaims that production never reclaims in time | `pressure` | Every verdict sample is post-GC; the peaks are sampled under load, and a ceiling every settled cycle comes back to is a regime, not an episode |
 | Native/buffer memory with a flat JS heap | `leak (external)` or an explicit RSS note | Heap, `external` and RSS are sampled and judged separately |
 | A leak in your code vs a dependency vs Next itself | `culprit: src/app/x/page.tsx (your code)` — or the package, or framework internals | Retainer chains mapped through the build's source maps |
 | A run whose own evidence is weak | `low confidence` warnings, or the verdict is withdrawn | Every run audits itself: did the load land, did the heap settle, does one cycle carry the average, did the heap run into its own ceiling |
@@ -277,6 +278,27 @@ separates them, because each one has a different fix:
   draft is generated. When the load was driving a cache with keys it had never
   served, the report says so on any growing route and points at `{n%N}` to
   bound the key set — measure again that way before believing the number.
+- **`pressure`** — nothing is retained, and the process is still heading for a
+  ceiling. Every sample a verdict is computed from is taken after a forced GC,
+  and production runs none of those, so the retention verdicts above are
+  structurally blind to memory a full collection *does* reclaim but that the
+  runtime does not reclaim fast enough on its own. This is that case: the
+  post-GC curve is flat or falling, the peak sampled under load is far above
+  what the route retains, **and** every settled cycle reaches that height. On
+  the reproduction for [#92287](https://github.com/vercel/next.js/issues/92287)
+  the app allocated about 1 MB of `arrayBuffers` per request, passed 3 GB and
+  was OOM-killed — and the old verdict was `stable`, which is precisely the trap
+  this tool exists to warn other people about. A single high peak is *not* this:
+  one cycle that reached a ceiling for a reason that did not repeat stays
+  `stable` with a peak note, because an episode is not a regime. What separates
+  this from an app entitled to a large working set is not the shape of the
+  curve, it is that a working set survives the forced collection and lands in
+  what the route retains, which acquits it on the ratio alone. These
+  routes are not measured again (the run already saw the ceiling it is
+  reporting) and get no issue draft: the finding is real, but it is not
+  retention, so there is nothing for a snapshot diff to name. The fix is
+  usually allocation rate, response size or concurrency, not a missing
+  `delete`.
 - **`inconclusive`** — the evidence does not decide. The run does not stop there: any inconclusive route is **measured again automatically**, with twice the cycles, and the second pass is what you see (`resolved at 8 cycles` next to the verdict). On the reproduction for [#95094](https://github.com/vercel/next.js/issues/95094), `--quick` alone reports `inconclusive` on three deltas and then comes back with the leak. `--no-resolve` turns the second pass off; when even that is undecided, the re-run command is still printed.
 - **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design. A process that died of **heap exhaustion** is not one of these: it reports `leak`, because a route that could not survive its own load did not fail to be measured — it was measured right up to the point where it stopped fitting. The verdict comes from that outcome, not from the shape of the truncated curve, which is the same rule `next-leak build` applies to a static-generation worker that dies. The run prints the cycles it survived and the growth up to the death, and exits 0 with a finding rather than 1 with an error.
 
@@ -303,9 +325,26 @@ That is a real measurement of the reproduction in
 app on 16.3.1 under a shorter profile still reaches 544 MB against 33.8 MB
 retained, so the shape has not gone anywhere. 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.
+and above 512 MB. A peak is the highest value *sampled* (every 250 ms), so it
+is a lower bound.
+
+A single high peak stays a note and leaves the verdict alone: one cycle that
+reached a ceiling may have reached it for a reason that will not happen again.
+When **every settled cycle** comes back to that height the verdict becomes
+[`pressure`](#reading-the-verdicts) instead, because at that point the run is no
+longer describing an episode, it is describing what the route does under load —
+which is the number a container is sized against. The peak is not required to
+climb, and asking it to would make the verdict unreachable: each cycle is
+preceded by a forced collection and runs the same traffic, so the peak converges
+on traffic × cost-per-request rather than ramping. Measured on the #92287
+reproduction on 2026-09-24, the rss peaks across four cycles were 1229, 1344,
+1369 and 1379 MB — an asymptote.
+
+What the route retains, for this ratio, is the **floor** of its post-GC cycle
+samples rather than the last of them. Those samples follow a forced collection
+but can still carry memory the collector had not reached yet, and on that same
+reproduction they swung between 45 MB and 217 MB inside a single run, which by
+itself decided whether the note appeared at all.
 
 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

package/dist/bootstrap.js

@@ -3,6 +3,8 @@ import "./chunk-6XYFBOL2.js";
 
 // src/bootstrap.ts
 import { mkdir, writeFile } from "fs/promises";
+import http2 from "http";
+import https from "https";
 import path2 from "path";
 
 // src/control-server.ts
@@ -21,6 +23,7 @@ async function forceGc(passes = 3) {
   }
   return true;
 }
+var requestProbe = globalThis;
 function sampleMemory(gcExposed) {
   const usage = process.memoryUsage();
   return {
@@ -28,7 +31,12 @@ function sampleMemory(gcExposed) {
     heapUsed: usage.heapUsed,
     rss: usage.rss,
     external: usage.external,
-    arrayBuffers: usage.arrayBuffers
+    arrayBuffers: usage.arrayBuffers,
+    pid: process.pid,
+    ppid: process.ppid,
+    argv: process.argv,
+    cwd: process.cwd(),
+    ...requestProbe.__nextLeakServedRequests === void 0 ? {} : { servedRequests: requestProbe.__nextLeakServedRequests }
   };
 }
 async function startControlServer(options) {
@@ -88,12 +96,30 @@ async function startControlServer(options) {
   };
 }
 
+// src/request-probe.ts
+function countServedRequests(module) {
+  const original = module.createServer;
+  module.createServer = function patched(...args) {
+    const server = original.apply(this, args);
+    server.on("request", () => {
+      requestProbe.__nextLeakServedRequests = (requestProbe.__nextLeakServedRequests ?? 0) + 1;
+    });
+    return server;
+  };
+}
+
 // src/bootstrap.ts
 var workDir = process.env["NEXT_LEAK_DIR"];
+function installRequestProbe() {
+  requestProbe.__nextLeakServedRequests = 0;
+  countServedRequests(http2);
+  countServedRequests(https);
+}
 if (workDir !== void 0 && workDir !== "") {
   try {
     await mkdir(workDir, { recursive: true });
     const server = await startControlServer({ snapshotDir: workDir });
+    installRequestProbe();
     await writeFile(
       path2.join(workDir, `control-${process.pid}.json`),
       JSON.stringify({ port: server.port, pid: process.pid })

package/dist/{chunk-4FYSLLSX.js → chunk-4NKGNMEA.js}

@@ -106,13 +106,17 @@ function classifyMemoryTrend(heapSamples, externalSamples, options = {}) {
   const external = classifyTrend(externalSamples, options);
   const severity = {
     leak: 0,
-    inconclusive: 1,
-    saturating: 2,
-    stable: 3
+    pressure: 1,
+    inconclusive: 2,
+    saturating: 3,
+    stable: 4
   };
   if (severity[external.verdict] < severity[heap.verdict]) {
     return { ...external, source: "external" };
   }
+  if (severity[external.verdict] === severity[heap.verdict] && external.growthPerCycle > heap.growthPerCycle) {
+    return { ...external, source: "external" };
+  }
   return heap;
 }
 
@@ -125,7 +129,8 @@ var VERDICT_WEAKENING = /* @__PURE__ */ new Set([
   "near-threshold",
   "spiky-growth",
   "thin-evidence",
-  "repetitions-disagree"
+  "repetitions-disagree",
+  "cache-residency"
 ]);
 function warrantsIssueDraft(report) {
   return effectiveVerdict(report) === "leak" && !report.confidence.warnings.some((warning) => VERDICT_WEAKENING.has(warning.code));
@@ -275,6 +280,15 @@ function thinEvidenceWarnings(trend, minGrowth) {
     detail: `judged on ${trend.deltas.length} cycles, and its weakest grew ${mb(smallest)} against a ${mb(minGrowth)} gate \u2014 on that few cycles ordinary oscillation reaches that, and a repeat run often disagrees; measure more cycles to resolve it`
   }];
 }
+function cacheResidencyWarnings(trend, revalidatesFromCache) {
+  if (trend.cacheDriven !== true || trend.verdict !== "leak" || revalidatesFromCache !== true) {
+    return [];
+  }
+  return [{
+    code: "cache-residency",
+    detail: `every request asked this ISR route for a key it had never cached, so storing them is part of the ${mb(trend.growthPerCycle)}/cycle \u2014 and here the usual remedy does not apply: bounding the keys ({n%N}) hands the requests back to the ISR cache, so the run would drive revalidation and measure Next's other path rather than a cleaner version of this one. Run it both ways and compare before attributing this to anyone`
+  }];
+}
 function isVerdictInvalid(input) {
   if (input.trend.verdict !== "leak") {
     return false;
@@ -295,6 +309,7 @@ function assessConfidence(input) {
     ...growthShapeWarnings(input.trend),
     ...noiseFloorWarnings(input.trend, minGrowth),
     ...thinEvidenceWarnings(input.trend, minGrowth),
+    ...cacheResidencyWarnings(input.trend, input.revalidatesFromCache),
     ...heapCeilingWarnings(input),
     ...warmUpBaselineWarnings(input)
   ];

package/dist/{chunk-72SHITHC.js → chunk-5VXBMWDN.js}

@@ -7,11 +7,13 @@ import {
   minGrowthFor,
   resolveCycles,
   warrantsIssueDraft
-} from "./chunk-4FYSLLSX.js";
+} from "./chunk-4NKGNMEA.js";
 import {
   assessPeakPressure,
-  describePeakPressure
-} from "./chunk-XHPUAMJG.js";
+  assessPressureVerdict,
+  describePeakPressure,
+  retainedAfterLoad
+} from "./chunk-E464SO7G.js";
 import {
   __commonJS,
   __esm,
@@ -94047,6 +94049,14 @@ var encodeSegment = (value) => restoreMarkers(encodeURIComponent(value).split(EN
 var ENCODED_BOUNDED = /%7Bn%25(\d+)%7D/gi;
 var restoreMarkers = (value) => value.replace(ENCODED_BOUNDED, (_match, bound) => `{n%${bound}}`);
 var encodeCatchAll = (value) => value.split("/").map(encodeSegment).join("/");
+function mixesMarkers(requestPath) {
+  return requestPath.includes(UNIQUE_MARKER) && boundedMarkerOf(requestPath) !== null;
+}
+function probeRequestPath(requestPath) {
+  const bounded = boundedMarkerOf(requestPath);
+  const withBound = bounded === null ? requestPath : requestPath.split(bounded.marker).join("0");
+  return withBound.split(UNIQUE_MARKER).join("0");
+}
 function resolveRoutePath(routeTemplate, config) {
   const resolved = [];
   for (const segment of routeTemplate.split("/")) {
@@ -94189,7 +94199,12 @@ var sampleSchema = z5.object({
   heapUsed: z5.number(),
   rss: z5.number(),
   external: z5.number(),
-  arrayBuffers: z5.number()
+  arrayBuffers: z5.number(),
+  pid: z5.number(),
+  ppid: z5.number(),
+  argv: z5.array(z5.string()),
+  cwd: z5.string(),
+  servedRequests: z5.number().optional()
 });
 var snapshotResponseSchema = z5.object({ file: z5.string(), sample: sampleSchema });
 var ControlError = class extends Error {
@@ -94560,8 +94575,10 @@ async function runRitual(options, deps = defaultDeps) {
     bootstrapPath: options.bootstrapPath,
     // Wait on the route this ritual is about to measure. `/` is a different
     // page with different failure modes, and readiness judged on it withdrew
-    // routes that were serving fine (#74).
-    readyPath: options.route,
+    // routes that were serving fine (#74). Markers resolved, so the probe asks
+    // for a key the load will also ask for rather than planting a literal
+    // `{n}` in the route's cache.
+    readyPath: probeRequestPath(options.route),
     ...options.maxOldSpaceMb !== void 0 && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...options.readyTimeoutMs !== void 0 && { readyTimeoutMs: options.readyTimeoutMs }
   };
@@ -94713,7 +94730,16 @@ async function runRitual(options, deps = defaultDeps) {
       baselineSnapshot,
       afterSnapshot,
       ...snapshotFailure !== void 0 && { snapshotFailure },
-      trend: classifyMemoryTrend(samples, externalSamples, trendOptions),
+      // A forced GC runs before every sample above, and production runs none.
+      // The peaks are the only readings in this result taken under load, so
+      // this is the one place that can tell a route which retains nothing from
+      // a route which retains nothing and dies anyway.
+      trend: assessPressureVerdict({
+        trend: classifyMemoryTrend(samples, externalSamples, trendOptions),
+        peaks,
+        retainedHeapBytes: retainedAfterLoad(memorySamples) ?? 0,
+        maxOldSpaceMb: options.maxOldSpaceMb ?? RITUAL_DEFAULTS.maxOldSpaceMb
+      }),
       requestsPerCycle: loadRequests,
       minGrowthPerCycle
     };
@@ -94917,7 +94943,8 @@ var VERDICT_ICON = {
   leak: "\u2716",
   stable: "\u2714",
   inconclusive: "?",
-  saturating: "~"
+  saturating: "~",
+  pressure: "\u25B2"
 };
 var RSS_MIN_GROWTH_PER_CYCLE = 16 * MB2;
 var RSS_MIN_TOTAL_GROWTH = 64 * MB2;
@@ -94943,8 +94970,14 @@ function ownerLabel(attribution) {
   }
 }
 function revalidationLines(route) {
-  return route.revalidatedEverySeconds === void 0 ? [] : [
-    `      driven through ISR revalidation (revalidates every ${route.revalidatedEverySeconds}s; without it the load would serve the cache)`
+  if (route.revalidatedEverySeconds === void 0) {
+    return [];
+  }
+  const every = `revalidates every ${route.revalidatedEverySeconds}s`;
+  return route.revalidationDriven === true ? [
+    `      driven through ISR revalidation (${every}; without it the load would serve the cache) \u2014 this is Next's revalidation path, so a leak that only happens on the path your users take is not in this number`
+  ] : [
+    `      not driven (${every}), because every request asks for a key this route has never cached \u2014 the load reached the renderer through the path your users take`
   ];
 }
 function repetitionLines(route) {
@@ -94971,9 +95004,22 @@ function cacheLines(route) {
     lines.push(
       `      the load served keys this route had never cached, so some of this growth is cache residency; bound it with {n%N} in next-leak.config.json`
     );
+    if (route.revalidatedEverySeconds !== void 0) {
+      lines.push(
+        `      on this route {n%N} does not isolate that: a bounded key set is served from the ISR cache, so the run would drive revalidation and measure a different path. Compare the two runs rather than trusting either number alone`
+      );
+    }
   }
   return lines;
 }
+function pressureLines(verdict) {
+  if (verdict !== "pressure") {
+    return [];
+  }
+  return [
+    `      nothing was retained between cycles, so the rate above is flat: this verdict is about what the process reached while serving, which every sample here hides behind a forced GC that production never runs`
+  ];
+}
 function abandonLines(route) {
   if (route.abandon === void 0) {
     return [];
@@ -95002,7 +95048,7 @@ function memorySourceLines(route, verdict) {
       `      verdict comes from EXTERNAL memory (buffers, streams, fetch bodies), not the JS heap: external ${externalCurve}`
     );
   }
-  if (verdict === "stable" && hasSustainedRssGrowth(route.memorySamples)) {
+  if ((verdict === "stable" || verdict === "pressure") && hasSustainedRssGrowth(route.memorySamples)) {
     const rssCurve = route.memorySamples.map((sample) => formatMb(sample.rss)).join(" \u2192 ");
     lines.push(
       `      note: heap is flat but RSS grows ${formatGrowth(route.rssPer1000Requests)} \u2014 not a JS-heap leak (allocator, external buffers or fragmentation): RSS ${rssCurve}`
@@ -95037,7 +95083,7 @@ function findingLines(route) {
   return lines;
 }
 function peakPressureLines(route, parameters) {
-  const retained = route.memorySamples.at(-1)?.heapUsed;
+  const retained = retainedAfterLoad(route.memorySamples);
   if (retained === void 0) {
     return [];
   }
@@ -95084,6 +95130,7 @@ function routeLines(route, parameters) {
     ...repetitionLines(route),
     ...revalidationLines(route),
     ...cacheLines(route),
+    ...pressureLines(verdict),
     ...abandonLines(route),
     ...confidenceLines(route),
     ...memorySourceLines(route, verdict),
@@ -95304,6 +95351,9 @@ import { createServer } from "net";
 import path9 from "path";
 
 // src/isr.ts
+function keysAreNewEveryRequest(requestPath) {
+  return requestPath.includes(UNIQUE_MARKER) && boundedMarkerOf(requestPath) === null;
+}
 var REVALIDATE_HEADER = "x-prerender-revalidate";
 function revalidateSecondsFor(manifest, route) {
   const routes = manifest?.routes;
@@ -95324,7 +95374,7 @@ function revalidateSecondsFor(manifest, route) {
 function revalidates(manifest, route) {
   return revalidateSecondsFor(manifest, route) !== null;
 }
-function planRevalidation(manifest, route, userHeaders) {
+function planRevalidation(manifest, route, userHeaders, requestPath) {
   const userSupplied = Object.keys(userHeaders ?? {}).some(
     (name) => name.toLowerCase() === REVALIDATE_HEADER
   );
@@ -95334,6 +95384,9 @@ function planRevalidation(manifest, route, userHeaders) {
   if (!revalidates(manifest, route)) {
     return { kind: "not-isr" };
   }
+  if (requestPath !== void 0 && keysAreNewEveryRequest(requestPath)) {
+    return { kind: "no-cache-to-drive" };
+  }
   const previewModeId = manifest?.preview?.previewModeId;
   if (previewModeId === void 0 || previewModeId === "") {
     return {
@@ -95447,15 +95500,18 @@ function skipReason(route, requestPath) {
   if (requestPath === null) {
     return "needs sample params for dynamic segments (next-leak.config.json)";
   }
+  if (mixesMarkers(requestPath)) {
+    return `mixes "{n}" and "{n%N}" across its params in next-leak.config.json \u2014 the load resolves one and sends the other as a literal, so every request would ask for a path with "{n}" in it. Pick one cardinality for the whole route.`;
+  }
   return null;
 }
 async function measureRoute(context, route, requestPath, index, pass = void 0) {
   const { deps, options, target, workDir, routeConfig, registry, nextVersion, progress } = context;
-  const plan = planRevalidation(target.prerender, route.path, routeConfig.headers);
+  const plan = planRevalidation(target.prerender, route.path, routeConfig.headers, requestPath);
   const revalidateSeconds = revalidateSecondsFor(target.prerender, route.path);
   const bounded = boundedMarkerOf(requestPath);
   const driven = plan.kind === "drive" ? plan.headers : {};
-  const cacheDriven = plan.kind === "drive" && bounded === null;
+  const cacheDriven = plan.kind === "no-cache-to-drive" || plan.kind === "drive" && bounded === null;
   const merged = { ...driven, ...routeConfig.headers ?? {} };
   const headers = Object.keys(merged).length === 0 ? void 0 : merged;
   const result = await deps.ritual({
@@ -95493,6 +95549,9 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
     memorySamples: result.memorySamples,
     maxOldSpaceMb: options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB,
     warmupRequests: options.warmupRequests ?? RITUAL_DEFAULTS.warmupRequests,
+    // Decides whether the cache-residency remedy exists on this route: bounding
+    // the keys of an ISR route hands the requests back to the cache.
+    revalidatesFromCache: revalidateSeconds !== null,
     ...routeConfig.abandonAfterMs !== void 0 && {
       abandonAfterMs: routeConfig.abandonAfterMs
     },
@@ -95512,7 +95571,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
       detail: result.snapshotFailure
     };
     progress(`no snapshot to attribute for ${route.path}: ${result.snapshotFailure}`);
-  } else if (verdict !== "stable" || options.diffAll === true) {
+  } else if (verdict !== "stable" && verdict !== "pressure" || options.diffAll === true) {
     progress(`diffing snapshots for ${route.path}`);
     try {
       diff = await deps.diff(result.baselineSnapshot, result.afterSnapshot);
@@ -95535,6 +95594,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
     memorySamples: result.memorySamples,
     peaks: result.peaks,
     ...revalidateSeconds !== null && { revalidatedEverySeconds: revalidateSeconds },
+    ...plan.kind === "drive" && { revalidationDriven: true },
     ...bounded !== null && { keyCardinality: bounded.bound },
     unreclaimedSamples: result.unreclaimedSamples,
     unreclaimedTrend: result.unreclaimedTrend,
@@ -95561,8 +95621,8 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-O7ILFOF5.js");
-  const { renderIssueMarkdown } = await import("./issue-report-FPVOZ6HU.js");
+  const { renderHtmlReport } = await import("./html-report-6KGPHCMA.js");
+  const { renderIssueMarkdown } = await import("./issue-report-OALZZLVR.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
       const file = path9.join(workDir, `ISSUE-${routeSlug(route.route)}.md`);
@@ -95594,7 +95654,12 @@ async function routeReportFor(context, route, index, total) {
     progress(`skipping ${label}: ${reason ?? "needs sample params"}`);
     return { route: route.path, status: "skipped", reason: reason ?? "needs sample params" };
   }
-  const plan = planRevalidation(context.target.prerender, route.path, routeConfig.headers);
+  const plan = planRevalidation(
+    context.target.prerender,
+    route.path,
+    routeConfig.headers,
+    requestPath
+  );
   if (plan.kind === "cannot-drive") {
     progress(`not measuring ${label}: ${plan.reason}`);
     return { route: route.path, status: "not-exercised", reason: plan.reason };
@@ -95609,6 +95674,7 @@ function reasonToResolve(verdict) {
       return "growth was still decelerating when the window ran out";
     case "leak":
     case "stable":
+    case "pressure":
       return null;
   }
 }

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-72SHITHC.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-72SHITHC.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.3",
+  "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",