next-leak 0.1.0

package/dist/cli-args.d.ts

@@ -0,0 +1,24 @@
+export type CliRunOptions = {
+    appDir: string;
+    routes: string[] | null;
+    cycles: number | null;
+    requests: number | null;
+    connections: number | null;
+    idleSeconds: number | null;
+    quick: boolean;
+    diffAll: boolean;
+    output: string | null;
+};
+export type ParsedCli = {
+    kind: "run";
+    options: CliRunOptions;
+} | {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "error";
+    message: string;
+};
+export declare function helpText(version: string): string;
+export declare function parseCliArgs(argv: string[]): ParsedCli;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+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 {
+  RouteConfigError,
+  TargetError,
+  checkRuntime,
+  formatReport,
+  helpText,
+  killActiveChildren,
+  parseCliArgs,
+  runMeasurement
+} from "./chunk-UZTZWHKH.js";
+import "./chunk-K5PZFVJH.js";
+import "./chunk-OSZ6ND6E.js";
+
+// src/cli.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var HEADROOM_SENTINEL = "NEXT_LEAK_WITH_HEADROOM";
+var HEADROOM_MB = 8192;
+function hasHeapHeadroom() {
+  return process.execArgv.some((argument) => argument.includes("--max-old-space-size")) || (process.env.NODE_OPTIONS ?? "").includes("--max-old-space-size") || process.env[HEADROOM_SENTINEL] === "1";
+}
+function reexecWithHeadroom() {
+  const child = spawn(process.execPath, [`--max-old-space-size=${HEADROOM_MB}`, ...process.argv.slice(1)], {
+    stdio: "inherit",
+    env: { ...process.env, [HEADROOM_SENTINEL]: "1" }
+  });
+  for (const signalName of ["SIGINT", "SIGTERM"]) {
+    process.on(signalName, () => child.kill(signalName));
+  }
+  child.once("exit", (code, signal) => {
+    process.exit(code ?? (signal === "SIGINT" ? 130 : 1));
+  });
+}
+async function main() {
+  const parsed = parseCliArgs(process.argv.slice(2));
+  if (parsed.kind === "version") {
+    console.log(version);
+    return;
+  }
+  if (parsed.kind === "help") {
+    console.log(helpText(version));
+    process.exitCode = process.argv.length > 2 ? 0 : 1;
+    return;
+  }
+  if (parsed.kind === "error") {
+    console.error(`error: ${parsed.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const guardFailure = checkRuntime();
+  if (guardFailure !== null) {
+    console.error(`error: ${guardFailure}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!hasHeapHeadroom()) {
+    reexecWithHeadroom();
+    return;
+  }
+  const aborter = new AbortController();
+  let interrupts = 0;
+  for (const signalName of ["SIGINT", "SIGTERM"]) {
+    process.on(signalName, () => {
+      interrupts += 1;
+      if (interrupts > 1) {
+        process.exit(130);
+      }
+      console.error("\n\xB7 interrupted \u2014 stopping the measured process and writing a partial run.json");
+      aborter.abort();
+      killActiveChildren();
+    });
+  }
+  const { options } = parsed;
+  const quickPreset = options.quick ? { loadRequests: 2e3, cycles: 4, idleMs: 8e3 } : {};
+  const report = await runMeasurement({
+    appDir: options.appDir,
+    bootstrapPath: fileURLToPath(new URL("./bootstrap.js", import.meta.url)),
+    signal: aborter.signal,
+    ...quickPreset,
+    ...options.routes !== null && { routeFilter: options.routes },
+    ...options.cycles !== null && { cycles: options.cycles },
+    ...options.requests !== null && { loadRequests: options.requests },
+    ...options.connections !== null && { connections: options.connections },
+    ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
+    ...options.diffAll && { diffAll: true },
+    ...options.output !== null && { outputDir: options.output },
+    onProgress: (message) => console.error(`\xB7 ${message}`)
+  });
+  console.log(formatReport(report));
+  if (aborter.signal.aborted) {
+    process.exitCode = 130;
+  }
+}
+main().catch((cause) => {
+  if (cause instanceof TargetError || cause instanceof RouteConfigError) {
+    console.error(`error: ${cause.message}`);
+  } else {
+    console.error(cause);
+  }
+  process.exitCode = 1;
+});

package/dist/confidence.d.ts

@@ -0,0 +1,78 @@
+import type { LoadOutcome, SettleOutcome } from "./ritual.js";
+import type { TrendResult, TrendVerdict } from "./trend.js";
+/**
+ * Why a measurement may not support its own verdict.
+ *
+ * `unsettled`           — the heap was still moving when sampled
+ * `settle-unverified`   — the idle budget was too short to check
+ * `load-incomplete`     — fewer requests landed than were asked for
+ * `abandon-ineffective` — early-disconnect run that disconnected nothing
+ * `abandon-before-response` — cut before the server sent a byte, so the
+ *   mid-stream teardown path was never reached
+ * `spiky-growth`        — one cycle dominates, so the mean describes little
+ * `near-threshold`      — growth barely clears the noise floor
+ */
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold";
+export type MeasurementWarning = {
+    code: WarningCode;
+    detail: string;
+};
+export type ConfidenceReport = {
+    level: "high" | "low";
+    warnings: MeasurementWarning[];
+    /**
+     * Verdict the evidence actually supports, when the measurement is not merely
+     * noisy but invalid. Only ever downgrades `leak`: accusing an app of leaking
+     * on evidence that does not hold is the expensive error — it sends someone
+     * chasing a ghost and ends as an issue against this tool.
+     */
+    supersededVerdict?: TrendVerdict;
+};
+export type ConfidenceInput = {
+    trend: TrendResult;
+    loadOutcomes: readonly LoadOutcome[];
+    settleOutcomes: readonly SettleOutcome[];
+    /** Set when the run asked for early disconnects. */
+    abandonAfterMs?: number;
+    /** Threshold the verdict used, for the noise-floor check. */
+    minGrowthPerCycle?: number;
+};
+/**
+ * The verdict a route's evidence actually supports.
+ *
+ * `trend.verdict` stays exactly as measured — the raw record must survive — so
+ * every consumer that shows a verdict to a human reads it through here
+ * instead, or it will report a leak the audit already withdrew.
+ *
+ * Structurally typed on purpose: it lives here, next to the audit, so the
+ * reporters can reach it without importing the runner (and, through it,
+ * memlab) just to render a line of text.
+ */
+export declare function effectiveVerdict(report: {
+    trend: TrendResult;
+    confidence: ConfidenceReport;
+}): TrendVerdict;
+/**
+ * Whether a route's evidence is solid enough to draft an issue for.
+ *
+ * Stricter than the verdict on purpose: a draft is written to be pasted into
+ * someone else's tracker, so it needs a leak that is plain, not one that
+ * merely cleared the threshold. Measuring a healthy route on a real app
+ * (`/server-plp`, 4 cycles × 2000 requests) produced deltas of
+ * [0.9, 0.25, 0.33] MB and a draft; at 8 cycles × 5000 the same route
+ * oscillated around a flat 39 MB and was plainly stable.
+ */
+export declare function warrantsIssueDraft(report: {
+    trend: TrendResult;
+    confidence: ConfidenceReport;
+}): boolean;
+/**
+ * Audits a route measurement against its own evidence.
+ *
+ * A leak detector is an instrument, and a miscalibrated instrument does not
+ * fail loudly — it reports confident, wrong numbers. Two implementations of
+ * early disconnects shipped in this repo that abandoned nothing, and both
+ * produced a verdict indistinguishable from the correct one; only the audit
+ * trail caught them. This turns that trail into a check that runs every time.
+ */
+export declare function assessConfidence(input: ConfidenceInput): ConfidenceReport;

package/dist/control-client.d.ts

@@ -0,0 +1,11 @@
+import type { HeapSample } from "./control-server.js";
+export declare class ControlError extends Error {
+    constructor(message: string);
+}
+/** Forces GC in the measured process and returns a settled memory sample. */
+export declare function requestGc(port: number): Promise<HeapSample>;
+/** Forces GC, writes a named heap snapshot, and returns its path and sample. */
+export declare function requestSnapshot(port: number, name: string): Promise<{
+    file: string;
+    sample: HeapSample;
+}>;

package/dist/control-server.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Forces garbage collection. A single pass is not enough to settle the heap;
+ * phase-0 measurements used 3 passes separated by event-loop ticks so that
+ * finalizers and pending callbacks can release references between passes.
+ * Returns false when the process was not started with `--expose-gc`.
+ */
+export declare function forceGc(passes?: number): Promise<boolean>;
+export type HeapSample = {
+    gcExposed: boolean;
+    heapUsed: number;
+    rss: number;
+    external: number;
+    arrayBuffers: number;
+};
+export declare function sampleMemory(gcExposed: boolean): HeapSample;
+export type ControlServerOptions = {
+    /** Directory where heap snapshots are written. */
+    snapshotDir: string;
+    /** Injectable for tests; defaults to `v8.writeHeapSnapshot`. */
+    writeSnapshot?: (file: string) => string;
+};
+export type ControlServer = {
+    port: number;
+    close: () => Promise<void>;
+};
+/**
+ * Internal control channel booted inside the measured app's process.
+ *
+ * - `GET /gc` — force GC, respond with a memory sample.
+ * - `GET /snapshot?name=<label>` — force GC, write `<label>.heapsnapshot`
+ *   into `snapshotDir`, respond `{ file, sample }` only once fully written.
+ */
+export declare function startControlServer(options: ControlServerOptions): Promise<ControlServer>;

package/dist/environment.d.ts

@@ -0,0 +1,11 @@
+export type MeasurementEnvironment = {
+    nodeVersion: string;
+    platform: string;
+    arch: string;
+    cpuModel: string | null;
+    totalMemoryBytes: number;
+    nextVersion: string | null;
+    nextLeakVersion: string;
+};
+/** A report without environment info is not reproducible — capture it once per run. */
+export declare function captureEnvironment(nextVersion: string | null): MeasurementEnvironment;

package/dist/guards.d.ts

@@ -0,0 +1,9 @@
+export type RuntimeFacts = {
+    nodeMajor: number;
+    platform: NodeJS.Platform;
+};
+/**
+ * Startup guards — fail with an actionable message before any process is
+ * spawned, instead of failing mid-run with an unrelated error.
+ */
+export declare function checkRuntime(facts?: RuntimeFacts): string | null;

package/dist/heap-diff.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Minimal structural view of a parsed heap snapshot. `@memlab`'s
+ * IHeapSnapshot satisfies it; tests use small hand-built graphs.
+ */
+export type HeapEdgeLike = {
+    type: string;
+    name_or_index: string | number;
+    fromNode: HeapNodeLike;
+};
+export type HeapNodeLike = {
+    id: number;
+    type: string;
+    name: string;
+    self_size: number;
+    retainedSize: number;
+    referrers: HeapEdgeLike[];
+    /** Outgoing edges; optional because test fixtures rarely need them. */
+    references?: Array<{
+        name_or_index: string | number;
+    }>;
+};
+export type HeapLike = {
+    nodes: {
+        forEach(callback: (node: HeapNodeLike) => void): void;
+    };
+};
+export type DiffOptions = {
+    /** Type-level deltas smaller than this are dropped. Default 20 KiB. */
+    minTypeDeltaBytes?: number;
+    /** Retained-size growth for an existing node to be reported. Default 100 KiB. */
+    grownThresholdBytes?: number;
+    /** Retained size for a new node to be considered. Default 2 KiB. */
+    newThresholdBytes?: number;
+    /**
+     * Baseline nodes with retained size below this floor are not tracked for
+     * growth — the memory guard that keeps the baseline summary small.
+     * Default 50 KiB.
+     */
+    bigRetainedFloorBytes?: number;
+    maxFindings?: number;
+    chainDepth?: number;
+};
+export type TypeDelta = {
+    type: string;
+    deltaBytes: number;
+};
+export type NodeFinding = {
+    kind: "grown" | "new";
+    nodeType: string;
+    name: string;
+    /** Retained-size delta for grown nodes; absolute retained size for new ones. */
+    retainedBytes: number;
+    retainerChain: string;
+    /** Bundler module ids seen along the chain (needs `resolveNumeric`). */
+    moduleIds: number[];
+};
+export type HeapDiff = {
+    typeDeltas: TypeDelta[];
+    grownNodes: NodeFinding[];
+    newNodes: NodeFinding[];
+};
+/**
+ * Compact summary of a baseline heap. This is all that stays resident after
+ * the baseline snapshot is parsed — never the heap itself.
+ */
+export type BaselineSummary = {
+    nodeIds: Set<number>;
+    bigRetained: Map<number, number>;
+    typeSelfSizes: Map<string, number>;
+};
+export declare function summarizeBaseline(heap: HeapLike, options?: DiffOptions): BaselineSummary;
+/**
+ * Walks referrers upward preferring strong, non-synthetic edges and refusing
+ * to revisit nodes, producing a single human-readable ownership chain.
+ */
+export declare function retainerChain(node: HeapNodeLike, depth: number): string;
+export declare function diffAgainstBaseline(baseline: BaselineSummary, after: HeapLike, options?: DiffOptions): HeapDiff;
+export declare class SnapshotError extends Error {
+    constructor(message: string);
+}
+/**
+ * Cheap structural check before handing a file to memlab.
+ *
+ * memlab does not throw on malformed input — it calls `process.exit(1)`,
+ * which no try/catch can intercept. Without this guard a truncated snapshot
+ * (disk full, process killed mid-write) killed the CLI outright and took a
+ * multi-hour run's results with it. Reads O(1) bytes, not the whole file.
+ */
+export declare function assertReadableSnapshot(file: string): Promise<void>;
+export type HeapLoader = (file: string) => Promise<HeapLike>;
+/**
+ * Diffs two snapshot files parsing them strictly sequentially: the baseline
+ * heap is reduced to its compact summary and released before the after heap
+ * is parsed, so at most one full heap graph is resident at any time.
+ */
+export declare function diffSnapshotFiles(baselineFile: string, afterFile: string, options?: DiffOptions, loadHeap?: HeapLoader): Promise<HeapDiff>;

package/dist/html-report-3JIRVRBF.js

@@ -0,0 +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-4BMPC45G.js";
+import "./chunk-K5PZFVJH.js";
+import "./chunk-OSZ6ND6E.js";
+export {
+  renderHtmlReport
+};

package/dist/html-report.d.ts

@@ -0,0 +1,3 @@
+import type { RunReport } from "./runner.js";
+/** Self-contained report page: renders offline, from file://, no requests. */
+export declare function renderHtmlReport(run: RunReport): string;

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export { classifyTrend } from "./trend.js";
+export type { TrendOptions, TrendResult, TrendVerdict } from "./trend.js";
+export { discoverRoutes, appPathsManifestSchema, routesManifestSchema } from "./manifests.js";
+export type { AppPathsManifest, DiscoveredRoute, RouteKind, RoutesManifest } from "./manifests.js";
+export { validateTarget, TargetError } from "./target.js";
+export type { TargetErrorCode, ValidatedTarget } from "./target.js";
+export { runLoadPhase, LoadError } from "./load.js";
+export type { LoadPhaseOptions, LoadPhaseResult } from "./load.js";
+export { runRitual } from "./ritual.js";
+export type { RitualDeps, RitualOptions, RitualResult } from "./ritual.js";
+export { launchInstrumented, LaunchError } from "./launcher.js";
+export type { LaunchedApp, LaunchOptions } from "./launcher.js";
+export { diffSnapshotFiles, diffAgainstBaseline, summarizeBaseline, retainerChain, assertReadableSnapshot, SnapshotError } from "./heap-diff.js";
+export type { DiffOptions, HeapDiff, HeapLike, NodeFinding, TypeDelta } from "./heap-diff.js";
+export { runMeasurement, freePort } from "./runner.js";
+export type { RouteReport, RunOptions, RunnerDeps, RunReport } from "./runner.js";
+export { formatReport } from "./report.js";
+export { extractModuleRegistry, extractChunkModules } from "./module-registry.js";
+export type { ModuleRegistry } from "./module-registry.js";
+export { decodeMappings, decodeVlqLine, sourceIndexAt } from "./vlq.js";
+export { attributeDiff, attributeFinding, classifySource } from "./attribution.js";
+export type { AttributedDiff, FindingAttribution, Owner, RouteAttribution } from "./attribution.js";
+export { loadSignatures, matchSignatures, readNextVersion } from "./signatures.js";
+export type { MatchedSignature, Signature } from "./signatures.js";
+export { captureEnvironment } from "./environment.js";
+export type { MeasurementEnvironment } from "./environment.js";
+export { renderHtmlReport } from "./html-report.js";
+export { renderIssueMarkdown } from "./issue-report.js";
+export type { MeasuredRoute } from "./issue-report.js";
+export { routeSlug } from "./runner.js";
+export type { RunParameters } from "./runner.js";
+export { loadRouteConfig, resolveRoutePath, RouteConfigError, ROUTE_CONFIG_FILE } from "./route-config.js";
+export type { RouteConfig } from "./route-config.js";
+export { checkRuntime } from "./guards.js";
+export { parseCliArgs, helpText } from "./cli-args.js";

package/dist/index.js

@@ -0,0 +1,95 @@
+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 {
+  LaunchError,
+  LoadError,
+  ROUTE_CONFIG_FILE,
+  RouteConfigError,
+  SnapshotError,
+  TargetError,
+  appPathsManifestSchema,
+  assertReadableSnapshot,
+  attributeDiff,
+  attributeFinding,
+  captureEnvironment,
+  checkRuntime,
+  classifySource,
+  classifyTrend,
+  decodeMappings,
+  decodeVlqLine,
+  diffAgainstBaseline,
+  diffSnapshotFiles,
+  discoverRoutes,
+  extractChunkModules,
+  extractModuleRegistry,
+  formatReport,
+  freePort,
+  helpText,
+  launchInstrumented,
+  loadRouteConfig,
+  loadSignatures,
+  matchSignatures,
+  parseCliArgs,
+  readNextVersion,
+  resolveRoutePath,
+  retainerChain,
+  routeSlug,
+  routesManifestSchema,
+  runLoadPhase,
+  runMeasurement,
+  runRitual,
+  sourceIndexAt,
+  summarizeBaseline,
+  validateTarget
+} from "./chunk-UZTZWHKH.js";
+import {
+  renderHtmlReport
+} from "./chunk-4BMPC45G.js";
+import "./chunk-K5PZFVJH.js";
+import {
+  renderIssueMarkdown
+} from "./chunk-5K4WEMIS.js";
+import "./chunk-OSZ6ND6E.js";
+export {
+  LaunchError,
+  LoadError,
+  ROUTE_CONFIG_FILE,
+  RouteConfigError,
+  SnapshotError,
+  TargetError,
+  appPathsManifestSchema,
+  assertReadableSnapshot,
+  attributeDiff,
+  attributeFinding,
+  captureEnvironment,
+  checkRuntime,
+  classifySource,
+  classifyTrend,
+  decodeMappings,
+  decodeVlqLine,
+  diffAgainstBaseline,
+  diffSnapshotFiles,
+  discoverRoutes,
+  extractChunkModules,
+  extractModuleRegistry,
+  formatReport,
+  freePort,
+  helpText,
+  launchInstrumented,
+  loadRouteConfig,
+  loadSignatures,
+  matchSignatures,
+  parseCliArgs,
+  readNextVersion,
+  renderHtmlReport,
+  renderIssueMarkdown,
+  resolveRoutePath,
+  retainerChain,
+  routeSlug,
+  routesManifestSchema,
+  runLoadPhase,
+  runMeasurement,
+  runRitual,
+  sourceIndexAt,
+  summarizeBaseline,
+  validateTarget
+};

package/dist/issue-report-AB62FRNM.js

@@ -0,0 +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-5K4WEMIS.js";
+import "./chunk-OSZ6ND6E.js";
+export {
+  renderIssueMarkdown
+};

package/dist/issue-report.d.ts

@@ -0,0 +1,10 @@
+import type { RouteReport, RunReport } from "./runner.js";
+export type MeasuredRoute = Extract<RouteReport, {
+    status: "measured";
+}>;
+/**
+ * Issue draft in the Next.js bug-template section order. The attribution
+ * gates the preamble: app/dependency-owned leaks warn against filing
+ * upstream; framework/unattributed leaks read as an upstream-ready draft.
+ */
+export declare function renderIssueMarkdown(route: MeasuredRoute, run: RunReport): string;

package/dist/launcher.d.ts

@@ -0,0 +1,39 @@
+export type LaunchOptions = {
+    /** Absolute path to the standalone `server.js` (or any PORT/HOSTNAME-honoring server). */
+    serverPath: string;
+    /** Directory for `control.json` and heap snapshots (`NEXT_LEAK_DIR`). */
+    workDir: string;
+    /** Port the measured app should listen on. */
+    appPort: number;
+    /** Path to the built bootstrap module loaded with `--import`. */
+    bootstrapPath: string;
+    hostname?: string;
+    maxOldSpaceMb?: number;
+    readyTimeoutMs?: number;
+    env?: Record<string, string>;
+};
+export type LaunchedApp = {
+    pid: number;
+    appPort: number;
+    controlPort: number;
+    /** SIGTERM, then SIGKILL after a grace period. Resolves when the child exited. */
+    close: () => Promise<void>;
+};
+export declare class LaunchError extends Error {
+    constructor(message: string);
+}
+/** Interrupt safety: no measured-app process may outlive the CLI. */
+export declare function killActiveChildren(): void;
+/**
+ * Turns a stack dump into a sentence when the cause is recognisable. Seen in
+ * the wild: a webpack `output: standalone` build that ships without
+ * `@swc/helpers`, which fails identically when started by hand — the tool is
+ * the messenger, and should say so instead of printing 20 lines of trace.
+ */
+export declare function explainStartupFailure(stderr: string): string;
+/**
+ * Spawns the measured server in a fresh child process with GC exposed and the
+ * control-channel bootstrap preloaded, and waits until both the app port and
+ * the control channel respond.
+ */
+export declare function launchInstrumented(options: LaunchOptions): Promise<LaunchedApp>;

package/dist/load.d.ts

@@ -0,0 +1,34 @@
+export type LoadPhaseOptions = {
+    url: string;
+    /** Total number of requests to send. */
+    amount: number;
+    connections: number;
+    /** Sent with every request (compression, cookies, auth). */
+    headers?: Record<string, string>;
+    /**
+     * Give up on each request after this many milliseconds, emulating clients
+     * that disconnect before the response arrives. Abandoned requests are
+     * expected, so they do not count against the error budget.
+     */
+    abandonAfterMs?: number;
+    /**
+     * Maximum tolerated ratio of non-2xx responses plus socket errors before
+     * the phase fails. A route that errors under load must fail the run, not
+     * silently measure garbage. Default: 0.01 (1%).
+     */
+    maxErrorRatio?: number;
+};
+export type LoadPhaseResult = {
+    sent: number;
+    ok2xx: number;
+    non2xx: number;
+    errors: number;
+    timeouts: number;
+    durationSeconds: number;
+};
+export declare class LoadError extends Error {
+    readonly result: LoadPhaseResult;
+    constructor(message: string, result: LoadPhaseResult);
+}
+/** Runs one bounded load phase and fails when the error budget is exceeded. */
+export declare function runLoadPhase(options: LoadPhaseOptions): Promise<LoadPhaseResult>;

package/dist/manifests.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+/** `.next/server/app-paths-manifest.json`: app path → server bundle. */
+export declare const appPathsManifestSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type AppPathsManifest = z.infer<typeof appPathsManifestSchema>;
+/** `.next/server/pages-manifest.json`: page path → server bundle. */
+export declare const pagesManifestSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type PagesManifest = z.infer<typeof pagesManifestSchema>;
+/** `.next/routes-manifest.json` — only the fields the tool relies on. */
+export declare const routesManifestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    basePath: z.ZodString;
+    staticRoutes: z.ZodArray<z.ZodObject<{
+        page: z.ZodString;
+        regex: z.ZodString;
+    }, z.core.$loose>>;
+    dynamicRoutes: z.ZodArray<z.ZodObject<{
+        page: z.ZodString;
+        regex: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type RoutesManifest = z.infer<typeof routesManifestSchema>;
+export type RouteKind = "page" | "route-handler";
+export type DiscoveredRoute = {
+    /** Request path, e.g. "/" or "/products/[id]". */
+    path: string;
+    kind: RouteKind;
+    /** True when the path needs sample param values before it can be requested. */
+    dynamic: boolean;
+    /** Set when the route exists but cannot be requested directly. */
+    unaddressableReason?: string;
+};
+/**
+ * Routes from a Pages Router build.
+ *
+ * Server-side leaks are not an App Router exclusive — vercel/next.js#95094
+ * leaks through Pages middleware — and refusing to read this manifest made
+ * next-leak fail with a raw ENOENT on any Pages-only app.
+ *
+ * Statically prerendered pages (`.html` bundles) are kept deliberately: they
+ * still travel the server's request path, so a leak there is a real finding,
+ * and dropping routes silently is worse than measuring a cheap one.
+ */
+export declare function discoverPagesRoutes(pages: PagesManifest): DiscoveredRoute[];
+export declare function discoverRoutes(appPaths: AppPathsManifest): DiscoveredRoute[];