next-leak 0.6.0 → 0.8.0

package/README.md

@@ -167,10 +167,19 @@ first try. When a run skips a route it prints the same fragment.
   load-balancer timeouts and bots do. Some leaks only exist on that path
   (`ServerResponse` retained after an early disconnect; the RSC tee branch in
   [#94919](https://github.com/vercel/next.js/issues/94919)). The clock starts
-  at the **first byte of the response**, not at the request — under load a
-  request-relative window cuts before the stream begins and tests a different
-  path. Small values are the point: `4` means "read the first chunk, then
-  vanish". Requests abandoned on purpose are not counted as failures.
+  at the **first byte of the response**, so the cut lands mid-stream however
+  long the route takes to answer. Small values are the point: `4` means "read
+  the first chunk, then vanish". Requests abandoned on purpose are not counted
+  as failures.
+- **`abandonFrom`** moves that clock to the request itself
+  (`"abandonFrom": "request"`). Use it for the opposite experiment: a client
+  that is already gone before the server produces anything. On a route slower
+  than the deadline the default never cuts early — against the reproduction
+  for [#84648](https://github.com/vercel/next.js/issues/84648), whose upstream
+  answers in 400 ms while its load generator cuts at 60 ms, first-byte reached
+  7% of requests and `request` reached all of them. It stays opt-in because a
+  deadline armed on connect loses the race to the first byte on fast routes,
+  which measures the wrong path silently.
 
 `run.json` records what every load phase actually did — requests sent,
 2xx, abandoned — so a run can be audited instead of trusted.
@@ -359,6 +368,17 @@ through the build's source maps.
   to projects using `experimental.workerThreads: true`: a worker thread has no
   resident memory of its own to sample, and the run says so instead of
   reporting a number that would be measuring the parent.
+- **`next-leak build <dir> --attribute`** additionally names *what* the worker
+  retained, by signalling it for a pair of heap snapshots. **Opt-in, and slow
+  by nature:** the signal makes the worker write its whole heap to disk, which
+  on the #97464 reproduction has stalled a build for minutes at a time and
+  once for an hour and a half. Use it on a reproduction you are investigating,
+  not on a build you need to finish. It also covers only a low slice of the
+  curve, and says which: a snapshot weighs roughly 0.4x to 0.8x the worker's
+  resident size, so past about a gigabyte it exceeds the 512 MB a V8 string can
+  hold and cannot be read back — both captures happen below that, and the
+  report states what share of the observed growth they span (19% on that
+  reproduction, whose worker peaks near 4 GB).
 - **Architectures:** verified on **arm64 and x64** (linux/amd64 in Docker) — same app, same parameters, same verdicts.
 - **Attribution** (naming the file) needs a Turbopack build with server sourcemaps — the Next 15+ default. On webpack builds the registry is empty by design and findings degrade to `unattributed` with raw retainer chains; measurement itself does not depend on it. Note that `output: "standalone"` + `--webpack` produced a bundle that could not start at all on `16.3.0-canary.90` (missing `@swc/helpers`), independently of this tool.
 - Empirically validated on Next **15.5.4, 16.0.x, 16.1.5, 16.2.x, 16.3.0/16.3.1 and 16.3-canary** (incl. Sentry, OpenTelemetry, PPR and i18n apps), against the public reproductions attached to real issues (open and since-fixed). Most recent measurements, 2026-08-17/18: the runtime path on 16.2.12 and 16.3.1-canary.18, the build path on 16.2.12 and 16.3.1. The contracts it relies on are stable since Next 13–14, but older versions are untested.

package/dist/abandon-load.d.ts

@@ -1,9 +1,17 @@
+/**
+ * Where the abandon deadline starts. `first-byte` puts the cut mid-stream
+ * whatever the route's latency; `request` puts it before the response exists,
+ * which is a different leak path and not reachable from the other origin.
+ */
+export type AbandonOrigin = "first-byte" | "request";
 export type AbandonPhaseOptions = {
     url: string;
     amount: number;
     connections: number;
-    /** Destroy the socket this many ms after the first byte of the response. */
+    /** Destroy the socket this many ms after the origin below. */
     abandonAfterMs: number;
+    /** Defaults to `first-byte`. */
+    abandonFrom?: AbandonOrigin;
     headers?: Record<string, string>;
 };
 export type AbandonPhaseResult = {
@@ -30,6 +38,8 @@ export type AbandonPhaseResult = {
  * a client goes away mid-flight (closed tabs, load-balancer timeouts, bots).
  *
  * Raw sockets keep this honest: write the request, wait for the response to
- * start, then wait `abandonAfterMs` and destroy the socket mid-stream.
+ * start, then wait `abandonAfterMs` and destroy the socket mid-stream. With
+ * `abandonFrom: "request"` the wait starts at the write instead, which is the
+ * only way to cut a route that has not begun answering yet.
  */
 export declare function runAbandonPhase(options: AbandonPhaseOptions): Promise<AbandonPhaseResult>;

package/dist/build-attribution.d.ts

@@ -0,0 +1,33 @@
+import { type AttributedDiff } from "./attribution.js";
+import type { BuildRunResult } from "./build-run.js";
+import { diffSnapshotFiles, type HeapDiff } from "./heap-diff.js";
+import { extractModuleRegistry } from "./module-registry.js";
+export type BuildAttribution = {
+    diff: HeapDiff;
+    attributed: AttributedDiff;
+    /** Modules the registry resolved. Zero means every finding stays unattributed. */
+    registrySize: number;
+    /** Share of the worker's observed growth the snapshot pair spans, 0 to 1. */
+    bracketed: number;
+    baselineRssBytes: number;
+    afterRssBytes: number;
+    /** Where the pair was stored, so the finding can be checked by hand. */
+    baselineFile: string;
+    afterFile: string;
+};
+export type BuildAttributionDeps = {
+    diff: typeof diffSnapshotFiles;
+    registry: typeof extractModuleRegistry;
+};
+/**
+ * Names what a build's worker retained, from the pair the run captured.
+ *
+ * Returns null rather than throwing on every failure path. A build measurement
+ * stands on its curve and its verdict; this is an addition to the report, and
+ * an addition that can fail must not be able to take the report with it.
+ *
+ * The registry is read from `.next/server` *after* the build, never during it:
+ * a half-written chunk can resolve a module id to the wrong source, and naming
+ * the wrong owner confidently is worse than naming none.
+ */
+export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | null>;

package/dist/build-report.d.ts

@@ -1,3 +1,4 @@
+import type { BuildAttribution } from "./build-attribution.js";
 import type { BuildRunResult } from "./build-run.js";
 /**
  * Renders the build report.
@@ -8,4 +9,4 @@ import type { BuildRunResult } from "./build-run.js";
  * still the honest axis here — it is what a CI runner's limit is enforced
  * against and what the OOM killer reads.
  */
-export declare function formatBuildReport(result: BuildRunResult): string;
+export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | null): string;

package/dist/build-run.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from "node:child_process";
+import { type CollectedPair } from "./build-snapshot.js";
 import { type BuildSample } from "./build-verdict.js";
 import { type ProcessTableSample } from "./process-tree.js";
 import type { TrendResult } from "./trend.js";
@@ -6,6 +7,19 @@ export type WorkerSeries = {
     pid: number;
     samples: BuildSample[];
 };
+export type BuildCapture = {
+    pid: number;
+    files: CollectedPair;
+    baselineRssBytes: number;
+    afterRssBytes: number;
+    /**
+     * Peak resident memory of *this* worker, not of the build. The share of
+     * growth the pair covers is quoted against the curve the findings came
+     * from, and on a multi-worker build the highest peak can belong to a worker
+     * nothing was captured from.
+     */
+    peakRssBytes: number;
+};
 export type BuildRunResult = {
     appDir: string;
     /**
@@ -31,12 +45,20 @@ export type BuildRunResult = {
     retentionPerPageBytes: number | null;
     /** True when a worker hit the V8 heap limit — the finding, not a failure. */
     heapExhausted: boolean;
+    /**
+     * The snapshot pair captured from a worker, when one was. Attribution is an
+     * addition to this report, never a precondition for it: every field above is
+     * produced whether or not capture worked.
+     */
+    capture: BuildCapture | null;
     strippedCapWarning: string | null;
     exitCode: number | null;
     output: string;
 };
 export type BuildRunOptions = {
     appDir: string;
+    /** Where a captured snapshot pair is moved to. Capture is skipped without it. */
+    workDir?: string;
     signal?: AbortSignal;
     onProgress?: (message: string) => void;
     /** Overrides `process.env` for the build. */
@@ -44,6 +66,7 @@ export type BuildRunOptions = {
 };
 export type BuildRunDeps = {
     spawnBuild: (appDir: string, env: NodeJS.ProcessEnv) => ChildProcess;
+    signalWorker: (pid: number) => void;
     sampleTable: () => Promise<ProcessTableSample>;
     now: () => number;
     sleep: (ms: number) => Promise<void>;

package/dist/build-snapshot.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Worker resident memory above which its heap snapshot stops being parseable.
+ *
+ * Measured on 2026-08-19 against the vercel/next.js#97464 reproduction, three
+ * points: a worker at 802 MB wrote 310 MB, at 1201 MB wrote 563 MB, and at
+ * 3010 MB wrote 2388 MB. The ratio is not flat — 0.39x, 0.47x, 0.79x — so the
+ * 512 MB a V8 string can hold is crossed somewhere just past 1 GB of RSS.
+ * A snapshot taken above this is written, costs the disk, and then cannot be
+ * read (see `assertReadableSnapshot`), which is the worst of both.
+ */
+export declare const PARSEABLE_WORKER_RSS_BYTES: number;
+export type CaptureStage = "waiting" | "baseline-taken" | "pair-taken" | "missed";
+export type CaptureDecision = "wait" | "take-baseline" | "take-after" | "give-up";
+/**
+ * Decides what to do with a worker at this resident size.
+ *
+ * Both snapshots have to happen low on the curve, which is not where the
+ * interesting memory is. That is forced by the parse limit above and is the
+ * central compromise of build-time attribution: the pair samples the start of
+ * the growth rather than bracketing it, so the report has to say how much of
+ * the curve it actually covers.
+ */
+export declare function decideCapture(rssBytes: number, stage: CaptureStage, baselineRssBytes?: number | null): CaptureDecision;
+export declare function snapshotsWrittenBy(pid: number, filenames: readonly string[]): string[];
+export type CollectedPair = {
+    baselineFile: string;
+    afterFile: string;
+};
+/**
+ * Moves a worker's two snapshots out of the project and into the run's own
+ * directory. They are the user's source tree's problem otherwise: V8 chose
+ * where to put them, and leaving half a gigabyte of them behind in a repo
+ * would be a poor trade for a measurement.
+ */
+export declare function collectSnapshotPair(appDir: string, outDir: string, pid: number): Promise<CollectedPair | null>;
+/**
+ * Deletes snapshots a run wrote and cannot use — a give-up after the baseline,
+ * or a worker whose pair never completed. Without this a failed capture leaves
+ * hundreds of megabytes in the user's project with no report referring to them.
+ */
+export declare function discardSnapshots(appDir: string, pid: number): Promise<void>;
+/**
+ * What share of the worker's observed growth the pair actually spans.
+ *
+ * Reported rather than hidden because the parse limit forces the pair low: on
+ * the #97464 reproduction the worker peaks near 3.3 GB and the pair cannot
+ * reach past 1 GB, so the attributed bytes explain a minority of the curve. A
+ * reader comparing the two numbers without this would conclude the rest went
+ * unexplained.
+ */
+export declare function bracketedShare(baselineRssBytes: number, afterRssBytes: number, peakRssBytes: number): number;
+export declare function registerPendingCapture(appDir: string, pid: number): void;
+export declare function clearPendingCapture(): void;
+/** Best effort, synchronous, and never throws: it runs on the way out. */
+export declare function discardPendingSnapshotsSync(): void;

package/dist/{chunk-22PBLCGO.js → chunk-EJ26OBZI.js}

@@ -113,7 +113,7 @@ function settleWarnings(outcomes) {
   }
   return warnings;
 }
-function abandonmentWarnings(outcome) {
+function abandonmentWarnings(outcome, abandonFrom) {
   const abandoned = outcome.abandoned ?? 0;
   if (outcome.sent > 0 && abandoned < outcome.sent * ABANDON_EFFECTIVE_FLOOR) {
     return [{
@@ -121,6 +121,9 @@ function abandonmentWarnings(outcome) {
       detail: `${outcome.phase} disconnected early on only ${abandoned} of ${outcome.sent} requests (${pct(abandoned, outcome.sent)}) \u2014 the early-disconnect path was largely not exercised`
     }];
   }
+  if (abandonFrom === "request") {
+    return [];
+  }
   const midStream = outcome.abandonedMidStream ?? 0;
   if (abandoned > 0 && midStream < abandoned * MID_STREAM_FLOOR) {
     return [{
@@ -130,11 +133,11 @@ function abandonmentWarnings(outcome) {
   }
   return [];
 }
-function loadWarnings(outcomes, abandonAfterMs) {
+function loadWarnings(outcomes, abandonAfterMs, abandonFrom) {
   const warnings = [];
   for (const outcome of outcomes) {
     if (abandonAfterMs !== void 0) {
-      warnings.push(...abandonmentWarnings(outcome));
+      warnings.push(...abandonmentWarnings(outcome, abandonFrom));
       continue;
     }
     const landed = outcome.ok2xx ?? 0;
@@ -246,7 +249,7 @@ function assessConfidence(input) {
   const minGrowth = input.minGrowthPerCycle ?? MIN_GROWTH_NOISE_FLOOR;
   const warnings = [
     ...settleWarnings(input.settleOutcomes),
-    ...loadWarnings(input.loadOutcomes, input.abandonAfterMs),
+    ...loadWarnings(input.loadOutcomes, input.abandonAfterMs, input.abandonFrom),
     ...growthShapeWarnings(input.trend),
     ...noiseFloorWarnings(input.trend, minGrowth),
     ...thinEvidenceWarnings(input.trend, minGrowth),