npm - next-leak - Versions diffs - 0.8.0 → 0.9.0 - Mend

next-leak 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +11 -5
package/dist/{chunk-RS3AO7HB.js → chunk-T7LM4Z33.js} +8 -0
package/dist/{chunk-LFGWGM5Z.js → chunk-UVA77PMC.js} +109 -15
package/dist/cli.js +24 -2
package/dist/{html-report-TN7PYVU4.js → html-report-5XMR3EXE.js} +1 -1
package/dist/index.js +2 -2
package/dist/launcher.d.ts +20 -1
package/dist/load.d.ts +19 -0
package/dist/ritual.d.ts +24 -0
package/dist/route-guidance.d.ts +19 -0
package/dist/runner.d.ts +22 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -142,14 +142,20 @@ Dynamic routes need sample params in `next-leak.config.json` in your app dir:
 ```json
 {
   "params": { "lang": "en" },
-  "routes": { "/products/[id]": { "id": "42" } },
+  "routes": { "/products/[id]": { "id": "42-{n}" } },
   "headers": { "accept-encoding": "gzip, br", "cookie": "session=..." }
 }
 ```
-`--write-config` generates that file for you, filling in values from paths your
-build already prerendered where it knows them, so it usually resolves on the
-first try. When a run skips a route it prints the same fragment.
+`--write-config` generates that file for you. It takes the *shape* of each value
+from paths your build already prerendered, and makes the value itself move:
+`post-0` becomes `post-{n}`. A value the build prerendered is the one value
+guaranteed not to measure anything — every request hits the same warm cache
+entry, so the route reads as flat whatever it retains, and that false negative
+lands on exactly the leaks being reported now (`use cache`, `cacheComponents`
+and ISR all key on the params). If your app answers 404 for params it never
+prerendered, the run says so through its non-2xx count; drop the marker then.
+When a run skips a route it prints the same fragment.
 ```json
 ```
@@ -215,7 +221,7 @@ separates them, because each one has a different fix:
   allocator, external-buffer or fragmentation problem, not a JS-heap leak.
 - **`leak`** — the report names the culprit when attribution resolves: your file (`culprit: src/app/x/page.tsx (your code)`), a dependency (package name), or framework internals. An `ISSUE-<route>.md` draft is generated **when the evidence plainly supports the verdict** — a `leak` carrying low-confidence warnings (growth barely over the threshold, one cycle dominating the mean, too few cycles for its size) gets the verdict but no draft, because a draft is written to be pasted into someone else's tracker. If the leak is app-owned, the draft tells you **not** to file it upstream.
 - **`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.
+- **`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.
 ## Peak pressure: `stable` is not the same as safe

package/dist/{chunk-RS3AO7HB.js → chunk-T7LM4Z33.js} RENAMED Viewed

@@ -80,6 +80,7 @@ function renderHtmlReport(run) {
   const measured = run.routes.filter((route) => route.status === "measured");
   const skipped = run.routes.filter((route) => route.status === "skipped");
   const failed = run.routes.filter((route) => route.status === "failed");
+  const exhausted = run.routes.filter((route) => route.status === "died-of-heap");
   const environment = run.environment;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8">
@@ -102,6 +103,13 @@ code{background:#f4f4f4;padding:0 4px;border-radius:3px}
   )} \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((route) => measuredSection(route, run.parameters)).join("\n")}
+${exhausted.map(
+    (route) => route.status !== "died-of-heap" ? "" : `<h2><span class="badge" style="background:#c0392b">leak</span> <code>${escapeHtml(
+      route.route
+    )}</code></h2>
+<p class="curve">Ran out of heap after ${route.cyclesCompleted} of ${route.cyclesRequested} cycles \xD7 ${route.requestsPerCycle} requests. Post-GC heap up to the death: ${route.memorySamples.map((sample) => `${(sample.heapUsed / MB).toFixed(1)} MB`).join(" \u2192 ")}</p>
+<p class="warn">${escapeHtml(route.reason)}</p>`
+  ).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-LFGWGM5Z.js → chunk-UVA77PMC.js} RENAMED Viewed

@@ -92692,8 +92692,11 @@ function explainStartupFailure(stderr) {
   return `stderr:
 ${stderr}`;
 }
+function stderrShowsHeapExhaustion(stderr) {
+  return /heap out of memory|Reached heap limit|Ineffective mark-compacts/i.test(stderr);
+}
 function explainRuntimeFailure(stderr, maxOldSpaceMb) {
-  if (/heap out of memory|Reached heap limit|Ineffective mark-compacts/i.test(stderr)) {
+  if (stderrShowsHeapExhaustion(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)}`;
@@ -92808,7 +92811,19 @@ ${stderrTailBuffer}`;
       pid: child.pid ?? -1,
       appPort: options.appPort,
       controlPort,
-      explainExit: () => exited ? explainRuntimeFailure(stderrWindow(), options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB) : null,
+      explainExit: () => {
+        if (!exited) {
+          return null;
+        }
+        const stderr = stderrWindow();
+        return {
+          reason: explainRuntimeFailure(
+            stderr,
+            options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB
+          ),
+          heapExhausted: stderrShowsHeapExhaustion(stderr)
+        };
+      },
       close: async () => {
         if (exited) {
           return;
@@ -93255,6 +93270,13 @@ function resolveRoutePath(routeTemplate, config) {
 // src/route-guidance.ts
 var PLACEHOLDER = "REPLACE-ME";
+function varyingValueFrom(prerendered) {
+  const numbered = /^(.*?)(\d+)$/.exec(prerendered);
+  if (numbered !== null && numbered[1] !== "") {
+    return `${numbered[1]}{n}`;
+  }
+  return `${prerendered}-{n}`;
+}
 function sampleValuesFromManifest(manifest, routeTemplate) {
   const routes = manifest?.routes;
   if (routes === void 0) {
@@ -93291,7 +93313,8 @@ function renderConfigSkeleton(routeTemplates, manifest = void 0) {
     const sampled = sampleValuesFromManifest(manifest, template);
     const values = {};
     for (const segment of segments) {
-      values[segment.name] = sampled?.[segment.name] ?? PLACEHOLDER;
+      const prerendered = sampled?.[segment.name];
+      values[segment.name] = prerendered === void 0 ? PLACEHOLDER : varyingValueFrom(prerendered);
     }
     routes[template] = values;
   }
@@ -93488,6 +93511,13 @@ function routeLines(route, parameters) {
   if (route.status === "not-exercised") {
     return [`  \u2013 ${route.route}  not exercised: ${route.reason}`];
   }
+  if (route.status === "died-of-heap") {
+    const curve2 = route.memorySamples.map((sample) => formatMb(sample.heapUsed)).join(" \u2192 ");
+    return [
+      `  ${VERDICT_ICON.leak} ${route.route}  leak  (ran out of heap after ${route.cyclesCompleted} of ${route.cyclesRequested} cycles)` + (curve2 === "" ? "" : `  heap ${curve2}`),
+      `      ${route.reason}`
+    ];
+  }
   const verdict = effectiveVerdict(route);
   const curve = route.samples.map(formatMb).join(" \u2192 ");
   const resolved = route.resolvedWithCycles === void 0 ? "" : `  (resolved at ${route.resolvedWithCycles} cycles)`;
@@ -93510,7 +93540,7 @@ function skippedGuidanceLines(report) {
   if (skeleton === null) {
     return [];
   }
-  const editing = hasPlaceholders(skeleton) ? ` Replace each ${"REPLACE-ME"} with a value that exists in your app.` : ` The values come from paths your build already prerendered.`;
+  const editing = hasPlaceholders(skeleton) ? ` Replace each ${"REPLACE-ME"} with a value that exists in your app.` : ` The shapes come from paths your build already prerendered; \`{n}\` makes every request use a different one, because reusing a prerendered value serves the warm cache and reads as flat whatever the route retains. Use \`{n%200}\` instead to revisit a fixed set of 200 keys, and drop the marker only if the app 404s on params it never prerendered.`;
   return [
     "",
     `${needConfig.length} route(s) need sample params. Write this to next-leak.config.json in the app directory:${editing}`,
@@ -93519,7 +93549,9 @@ function skippedGuidanceLines(report) {
 }
 function coverageLine(report) {
   const total = report.routes.length;
-  const measured = report.routes.filter((route) => route.status === "measured").length;
+  const measured = report.routes.filter(
+    (route) => route.status === "measured" || route.status === "died-of-heap"
+  ).length;
   if (measured === total) {
     return `measured all ${total} discovered route(s)`;
   }
@@ -93605,6 +93637,29 @@ async function describeRedirect(url) {
     return null;
   }
 }
+async function describeUnprerenderedParams(url) {
+  const bounded = boundedMarkerOf(url);
+  const marker = bounded === null ? UNIQUE_MARKER : bounded.marker;
+  if (!url.includes(marker)) {
+    return null;
+  }
+  const probe = async (value) => {
+    try {
+      const response = await fetch(url.split(marker).join(value), { redirect: "manual" });
+      return response.status;
+    } catch {
+      return null;
+    }
+  };
+  const [novel, familiar] = await Promise.all([probe("999999"), probe("0")]);
+  if (novel === null || familiar === null) {
+    return null;
+  }
+  if (novel === 404 && familiar >= 200 && familiar < 300) {
+    return `the sample value varies per request (\`${marker}\`) and this app answers 404 for params it never prerendered \u2014 the route itself is fine, the value is the problem. Bound it to the params your build did prerender (\`{n%N}\` with N of them), or drop the marker and accept that every request serves the same cached entry`;
+  }
+  return null;
+}
 function boundedRequestSequence(fullUrl, bounded) {
   const parsed = new URL(fullUrl);
   const template = fullUrl.slice(parsed.origin.length);
@@ -93656,9 +93711,9 @@ async function runLoadPhase(options) {
   const ratio = options.amount === 0 ? 0 : failures / options.amount;
   if (ratio > (options.maxErrorRatio ?? 0.01)) {
     const unanswered = failures - result.non2xx - result.errors - result.timeouts;
-    const redirect = result.non2xx > 0 ? await describeRedirect(options.url) : null;
+    const explained = result.non2xx > 0 ? await describeUnprerenderedParams(options.url) ?? await describeRedirect(options.url) : null;
     throw new LoadError(
-      `${failures} of ${options.amount} requests failed against ${options.url} (${result.non2xx} non-2xx, ${result.errors} errors, ${result.timeouts} timeouts` + (unanswered > 0 ? `, ${unanswered} with no recorded response` : "") + ")" + (redirect === null ? diagnoseFailure(result, options.connections) : ` \u2014 ${redirect}`),
+      `${failures} of ${options.amount} requests failed against ${options.url} (${result.non2xx} non-2xx, ${result.errors} errors, ${result.timeouts} timeouts` + (unanswered > 0 ? `, ${unanswered} with no recorded response` : "") + ")" + (explained === null ? diagnoseFailure(result, options.connections) : ` \u2014 ${explained}`),
       result
     );
   }
@@ -93870,6 +93925,14 @@ Host: ${target.host}\r
 // src/ritual.ts
 var MIN_POLLS_TO_JUDGE = 2;
+var HeapExhaustedError = class extends Error {
+  evidence;
+  constructor(message, evidence) {
+    super(message);
+    this.name = "HeapExhaustedError";
+    this.evidence = evidence;
+  }
+};
 var SETTLE_POLL_MS = 2e3;
 var SETTLE_TOLERANCE = 0.01;
 var PEAK_POLL_MS = 250;
@@ -94022,6 +94085,13 @@ async function runRitual(options, deps = defaultDeps) {
       timings.push({ phase, seconds: Math.round((Date.now() - started) / 100) / 10 });
     }
   };
+  const memorySamples = [];
+  const unreclaimedSamples = [];
+  let unreclaimedLost = false;
+  const peaks = [];
+  let afterSnapshot = "";
+  let baselineSnapshot = "";
+  let cyclesCompleted = 0;
   try {
     const routeUrl = `http://127.0.0.1:${app.appPort}${options.route}`;
     await timed(
@@ -94037,11 +94107,8 @@ async function runRitual(options, deps = defaultDeps) {
       "baseline snapshot",
       () => requestSnapshot(app.controlPort, "baseline")
     );
-    const memorySamples = [baseline.sample];
-    const unreclaimedSamples = [];
-    let unreclaimedLost = false;
-    const peaks = [];
-    let afterSnapshot = "";
+    memorySamples.push(baseline.sample);
+    baselineSnapshot = baseline.file;
     for (let cycle = 1; cycle <= cycles; cycle += 1) {
       await timed(`cycle ${cycle} load`, async () => {
         const poller = pollPeak(app.controlPort, `cycle ${cycle}`, deps);
@@ -94075,6 +94142,7 @@ async function runRitual(options, deps = defaultDeps) {
       } else {
         memorySamples.push(await requestGc(app.controlPort));
       }
+      cyclesCompleted = cycle;
     }
     const samples = memorySamples.map((sample) => sample.heapUsed);
     const externalSamples = memorySamples.map((sample) => sample.external);
@@ -94095,7 +94163,7 @@ async function runRitual(options, deps = defaultDeps) {
         unreclaimedSamples.map((sample) => sample.external),
         { minGrowthPerCycle }
       ),
-      baselineSnapshot: baseline.file,
+      baselineSnapshot,
       afterSnapshot,
       trend: classifyMemoryTrend(samples, externalSamples, { minGrowthPerCycle }),
       requestsPerCycle: loadRequests,
@@ -94104,7 +94172,18 @@ async function runRitual(options, deps = defaultDeps) {
   } catch (cause) {
     const death = app.explainExit();
     if (death !== null) {
-      throw new Error(death);
+      if (death.heapExhausted) {
+        throw new HeapExhaustedError(death.reason, {
+          memorySamples,
+          peaks,
+          unreclaimedSamples: unreclaimedLost ? [] : unreclaimedSamples,
+          cyclesCompleted,
+          cyclesRequested: cycles,
+          requestsPerCycle: loadRequests,
+          baselineSnapshot
+        });
+      }
+      throw new Error(death.reason);
     }
     throw cause;
   } finally {
@@ -94454,7 +94533,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-TN7PYVU4.js");
+  const { renderHtmlReport } = await import("./html-report-5XMR3EXE.js");
   const { renderIssueMarkdown } = await import("./issue-report-HKA26WNV.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
@@ -94503,6 +94582,21 @@ async function routeReportFor(context, route, index, total) {
       return first;
     }
   } catch (cause) {
+    if (cause instanceof HeapExhaustedError) {
+      progress(`leak ${label}: ${cause.message}`);
+      const { evidence } = cause;
+      return {
+        route: route.path,
+        status: "died-of-heap",
+        requestPath,
+        reason: cause.message,
+        memorySamples: evidence.memorySamples,
+        peaks: evidence.peaks,
+        cyclesCompleted: evidence.cyclesCompleted,
+        cyclesRequested: evidence.cyclesRequested,
+        requestsPerCycle: evidence.requestsPerCycle
+      };
+    }
     const failure = cause instanceof Error ? cause.message : String(cause);
     progress(`failed ${label}: ${failure}`);
     return { route: route.path, status: "failed", reason: failure };

package/dist/cli.js CHANGED Viewed

@@ -20,7 +20,7 @@ import {
   runMeasurement,
   unregisterChild,
   validateTarget
-} from "./chunk-LFGWGM5Z.js";
+} from "./chunk-UVA77PMC.js";
 import {
   classifyTrend
 } from "./chunk-EJ26OBZI.js";
@@ -263,6 +263,21 @@ function formatBuildReport(result, attribution = null) {
     );
     return lines.join("\n");
   }
+  function parentPeakLines(result2) {
+    const peak = result2.parentSamples.reduce(
+      (highest, sample) => Math.max(highest, sample.rssBytes),
+      0
+    );
+    if (peak === 0) {
+      return [];
+    }
+    const last = result2.parentSamples[result2.parentSamples.length - 1];
+    const ended = last === void 0 ? 0 : last.rssBytes;
+    return [
+      `      the build's own process peaked at ${mb(peak)} (ended at ${mb(ended)}) \u2014 reported, not judged:`,
+      `      it sheds while workers climb, so it is never added to the figure above`
+    ];
+  }
   if (result.status === "nothing-to-measure") {
     lines.push(
       `  \u2013 no static-generation worker ran, so there was nothing to measure`,
@@ -296,6 +311,7 @@ function formatBuildReport(result, attribution = null) {
   }
   lines.push(
     ...attributionLines(attribution),
+    ...parentPeakLines(result),
     "",
     `  peak worker rss ${mb(result.peakWorkerRssBytes)} \xB7 sampled from the process tree, so a`,
     `  spike shorter than the polling interval is not observed`
@@ -848,6 +864,10 @@ ${skeleton}`
   console.log(`wrote ${file}`);
   if (hasPlaceholders(skeleton)) {
     console.log("replace each REPLACE-ME with a value that exists in your app");
+  } else {
+    console.log(
+      "`{n}` gives every request a different value: a prerendered one serves the warm cache and reads as flat whatever the route retains. Use `{n%200}` to revisit a fixed set of keys, and drop the marker only if the app 404s on params it never prerendered."
+    );
   }
 }
 async function main() {
@@ -899,7 +919,9 @@ async function main() {
     process.exitCode = 130;
     return;
   }
-  if (!report.routes.some((route) => route.status === "measured")) {
+  if (!report.routes.some(
+    (route) => route.status === "measured" || route.status === "died-of-heap"
+  )) {
     console.error("error: no route was measured \u2014 nothing above is a verdict about your app");
     process.exitCode = 1;
   }

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

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

package/dist/index.js CHANGED Viewed

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

package/dist/launcher.d.ts CHANGED Viewed

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

package/dist/load.d.ts CHANGED Viewed

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

package/dist/ritual.d.ts CHANGED Viewed

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

package/dist/route-guidance.d.ts CHANGED Viewed

@@ -1,4 +1,23 @@
 import type { PrerenderManifest } from "./manifests.js";
+/**
+ * Turns a prerendered value into one that varies per request.
+ *
+ * A value the build already prerendered is the one value guaranteed *not* to
+ * measure anything: every request hits the same warm cache entry and the route
+ * reads as flat no matter what it retains. That is a silent false negative, and
+ * it lands on exactly the leaks being reported now — `use cache`,
+ * `cacheComponents` and ISR all key on the params
+ * (vercel/next.js#97938, #97776, #97424, #92287).
+ *
+ * The prerendered value is still the best hint available: it shows the shape
+ * the app accepts. So the shape is kept and only the tail is made to move —
+ * `post-0` becomes `post-{n}`, `seed` becomes `seed-{n}`.
+ *
+ * If the app answers 404 for params it never prerendered, the run says so
+ * loudly through its non-2xx count. A noisy 404 is a far better outcome than a
+ * quiet `stable`.
+ */
+export declare function varyingValueFrom(prerendered: string): string;
 /**
  * Sample values lifted from paths the build actually prerendered.
  *

package/dist/runner.d.ts CHANGED Viewed

@@ -18,6 +18,28 @@ export type RouteReport = {
     status: "failed";
     reason: string;
 }
+/**
+ * The measured process ran out of heap partway through. This is a verdict,
+ * not a failure: the route did not fit in the limit the run gave it, and the
+ * outcome decides regardless of the shape of the truncated curve — the same
+ * rule the build path applies to a static-generation worker that dies.
+ *
+ * Kept apart from `measured` because there is no after-snapshot and no
+ * complete trend, and dressing it as a full measurement would claim data
+ * that does not exist.
+ */
+ | {
+    route: string;
+    status: "died-of-heap";
+    requestPath: string;
+    reason: string;
+    /** Post-GC readings up to the death; may be as short as the baseline. */
+    memorySamples: HeapSample[];
+    peaks: PeakSample[];
+    cyclesCompleted: number;
+    cyclesRequested: number;
+    requestsPerCycle: number;
+}
 /**
  * The route was reachable, but the load could not have exercised the code
  * path it represents — so no verdict is emitted. Measuring an ISR route

package/package.json CHANGED Viewed

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