next-leak 0.1.3 → 0.2.0

package/dist/{chunk-2BQZCZ4Z.js → chunk-E5ZKAANQ.js}

@@ -1,5 +1,72 @@
 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);
 
+// src/trend.ts
+var MIN_GROWTH_NOISE_FLOOR = 256 * 1024;
+var MIN_GROWTH_PER_1000_REQUESTS = 51.2 * 1024;
+function minGrowthFor(requestsPerCycle) {
+  return Math.max(MIN_GROWTH_NOISE_FLOOR, MIN_GROWTH_PER_1000_REQUESTS * requestsPerCycle / 1e3);
+}
+var STEPWISE_MIN_GROWING_CYCLES = 2;
+var STEPWISE_MAX_DRAWDOWN_RATIO = 0.1;
+function maxDrawdown(samples) {
+  let peak = samples[1] ?? 0;
+  let worst = 0;
+  for (let i = 1; i < samples.length; i += 1) {
+    const value = samples[i] ?? 0;
+    peak = Math.max(peak, value);
+    worst = Math.max(worst, peak - value);
+  }
+  return worst;
+}
+function isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth) {
+  if (growingCycles < STEPWISE_MIN_GROWING_CYCLES || mean < minGrowth) {
+    return false;
+  }
+  const netGrowth = deltas.reduce((sum, delta) => sum + delta, 0);
+  if (netGrowth <= 0) {
+    return false;
+  }
+  return maxDrawdown(samples) <= netGrowth * STEPWISE_MAX_DRAWDOWN_RATIO;
+}
+function classifyTrend(samples, options = {}) {
+  const minGrowth = options.minGrowthPerCycle ?? MIN_GROWTH_NOISE_FLOOR;
+  if (samples.length < 4) {
+    return { verdict: "inconclusive", growthPerCycle: 0, deltas: [] };
+  }
+  const deltas = [];
+  for (let i = 2; i < samples.length; i += 1) {
+    const current = samples[i];
+    const previous = samples[i - 1];
+    if (current === void 0 || previous === void 0) {
+      return { verdict: "inconclusive", growthPerCycle: 0, deltas: [] };
+    }
+    deltas.push(current - previous);
+  }
+  const mean = deltas.reduce((sum, d) => sum + d, 0) / deltas.length;
+  const allGrow = deltas.every((d) => d >= minGrowth);
+  const anyFlatOrDown = deltas.some((d) => d <= 0);
+  const growingCycles = deltas.filter((d) => d >= minGrowth).length;
+  if (allGrow) {
+    return { verdict: "leak", growthPerCycle: mean, deltas, source: "heap" };
+  }
+  if (isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth)) {
+    return { verdict: "leak", growthPerCycle: mean, deltas, source: "heap" };
+  }
+  if (anyFlatOrDown || mean < minGrowth) {
+    return { verdict: "stable", growthPerCycle: mean, deltas, source: "heap" };
+  }
+  return { verdict: "inconclusive", growthPerCycle: mean, deltas, source: "heap" };
+}
+function classifyMemoryTrend(heapSamples, externalSamples, options = {}) {
+  const heap = classifyTrend(heapSamples, options);
+  const external = classifyTrend(externalSamples, options);
+  const severity = { leak: 0, inconclusive: 1, stable: 2 };
+  if (severity[external.verdict] < severity[heap.verdict]) {
+    return { ...external, source: "external" };
+  }
+  return heap;
+}
+
 // src/confidence.ts
 function effectiveVerdict(report) {
   return report.confidence.supersededVerdict ?? report.trend.verdict;
@@ -11,7 +78,6 @@ var VERDICT_WEAKENING = /* @__PURE__ */ new Set([
 function warrantsIssueDraft(report) {
   return effectiveVerdict(report) === "leak" && !report.confidence.warnings.some((warning) => VERDICT_WEAKENING.has(warning.code));
 }
-var DEFAULT_MIN_GROWTH = 256 * 1024;
 var LOAD_COMPLETION_FLOOR = 0.99;
 var ABANDON_EFFECTIVE_FLOOR = 0.9;
 var MID_STREAM_FLOOR = 0.1;
@@ -99,6 +165,23 @@ function noiseFloorWarnings(trend, minGrowth) {
     detail: `growth of ${mb(trend.growthPerCycle)}/cycle barely clears the ${mb(minGrowth)} threshold \u2014 raise --load-requests so the signal outgrows the noise`
   }];
 }
+var HEAP_CEILING_RATIO = 0.7;
+function heapCeilingWarnings(input) {
+  const samples = input.memorySamples;
+  const capMb = input.maxOldSpaceMb;
+  if (samples === void 0 || capMb === void 0 || samples.length === 0) {
+    return [];
+  }
+  const peak = Math.max(...samples.map((sample) => sample.heapUsed));
+  const capBytes = capMb * 1024 * 1024;
+  if (peak < capBytes * HEAP_CEILING_RATIO) {
+    return [];
+  }
+  return [{
+    code: "near-heap-ceiling",
+    detail: `the heap peaked at ${mb(peak)} against a ${capMb} MB cap (${pct(peak, capBytes)}) \u2014 the curve may have been clipped by the ceiling rather than by the app; re-run with a larger --max-old-space`
+  }];
+}
 function isVerdictInvalid(input) {
   if (input.trend.verdict !== "leak") {
     return false;
@@ -108,12 +191,13 @@ function isVerdictInvalid(input) {
   return neverSettled || abandonedNothing;
 }
 function assessConfidence(input) {
-  const minGrowth = input.minGrowthPerCycle ?? DEFAULT_MIN_GROWTH;
+  const minGrowth = input.minGrowthPerCycle ?? MIN_GROWTH_NOISE_FLOOR;
   const warnings = [
     ...settleWarnings(input.settleOutcomes),
     ...loadWarnings(input.loadOutcomes, input.abandonAfterMs),
     ...growthShapeWarnings(input.trend),
-    ...noiseFloorWarnings(input.trend, minGrowth)
+    ...noiseFloorWarnings(input.trend, minGrowth),
+    ...heapCeilingWarnings(input)
   ];
   return {
     level: warnings.length === 0 ? "high" : "low",
@@ -123,6 +207,9 @@ function assessConfidence(input) {
 }
 
 export {
+  minGrowthFor,
+  classifyTrend,
+  classifyMemoryTrend,
   effectiveVerdict,
   warrantsIssueDraft,
   assessConfidence

package/dist/{chunk-ZFYIR423.js → chunk-HAKKAIHN.js}

@@ -1,9 +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 {
   assessConfidence,
+  classifyMemoryTrend,
+  classifyTrend,
   effectiveVerdict,
+  minGrowthFor,
   warrantsIssueDraft
-} from "./chunk-2BQZCZ4Z.js";
+} from "./chunk-E5ZKAANQ.js";
 import {
   __commonJS,
   __esm,
@@ -91969,14 +91972,20 @@ var FLAGS = [
     argName: "<list>",
     help: "Only measure these routes \u2014 comma-separated templates or prefixes (e.g. /api,/dashboard)"
   },
-  { flag: "--cycles", value: "int", argName: "<n>", help: "Load cycles per route (default 3, minimum 3)" },
+  { flag: "--cycles", value: "int", argName: "<n>", help: "Load cycles per route (default 4, minimum 3)" },
   { flag: "--requests", value: "int", argName: "<n>", help: "Requests per cycle (default 5000)" },
   { flag: "--connections", value: "int", argName: "<n>", help: "Concurrent connections (default 100)" },
   { flag: "--idle", value: "int", argName: "<seconds>", help: "Idle seconds before each sample (default 30)" },
+  {
+    flag: "--max-old-space",
+    value: "int",
+    argName: "<mb>",
+    help: "Heap cap of each measured process (default 512) \u2014 raise it for apps whose working set is larger"
+  },
   {
     flag: "--quick",
     value: "none",
-    help: "Fast preset: 2000 requests x 4 cycles, 8s idle \u2014 the profile used for real-app validation"
+    help: "Fast preset: 2000 requests x 4 cycles, 8s idle \u2014 same cycle count as the default, less traffic per cycle"
   },
   { flag: "--diff-all", value: "none", help: "Diff snapshots for stable routes too (slow)" },
   { flag: "--output", value: "string", argName: "<dir>", help: "Where to write runs (default <app-dir>/.next-leak)" },
@@ -92015,8 +92024,10 @@ var LIMITS = {
   "--cycles": 100,
   "--requests": 1e6,
   "--connections": 1e4,
-  "--idle": 3600
+  "--idle": 3600,
+  "--max-old-space": 65536
 };
+var MIN_MAX_OLD_SPACE_MB = 128;
 function findSpec(argument) {
   return FLAGS.find((spec) => spec.flag === argument || spec.alias === argument);
 }
@@ -92044,10 +92055,16 @@ function applyNumericFlag(flag, value, options) {
   if (flag === "--cycles" && parsed < 3) {
     return flagError("the trend verdict needs at least 3 cycles (--cycles 3 or more)");
   }
+  if (flag === "--max-old-space" && parsed < MIN_MAX_OLD_SPACE_MB) {
+    return flagError(
+      `option "--max-old-space" needs at least ${MIN_MAX_OLD_SPACE_MB} MB (got ${parsed}) \u2014 below that the measured app cannot start`
+    );
+  }
   if (flag === "--cycles") options.cycles = parsed;
   if (flag === "--requests") options.requests = parsed;
   if (flag === "--connections") options.connections = parsed;
   if (flag === "--idle") options.idleSeconds = parsed;
+  if (flag === "--max-old-space") options.maxOldSpaceMb = parsed;
   return FLAG_OK;
 }
 function applyFlag(spec, value, options) {
@@ -92058,6 +92075,7 @@ function applyFlag(spec, value, options) {
     case "--requests":
     case "--connections":
     case "--idle":
+    case "--max-old-space":
       return applyNumericFlag(spec.flag, value, options);
     case "--quick":
       options.quick = true;
@@ -92113,6 +92131,7 @@ function parseCliArgs(argv) {
     requests: null,
     connections: null,
     idleSeconds: null,
+    maxOldSpaceMb: null,
     quick: false,
     diffAll: false,
     output: null
@@ -92162,6 +92181,7 @@ import path from "path";
 import { pathToFileURL } from "url";
 import { z } from "zod";
 var controlFileSchema = z.object({ port: z.number(), pid: z.number() });
+var DEFAULT_MAX_OLD_SPACE_MB = 512;
 var LaunchError = class extends Error {
   constructor(message) {
     super(message);
@@ -92209,7 +92229,7 @@ async function launchInstrumented(options) {
     process.execPath,
     [
       "--expose-gc",
-      `--max-old-space-size=${options.maxOldSpaceMb ?? 512}`,
+      `--max-old-space-size=${options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB}`,
       "--import",
       pathToFileURL(options.bootstrapPath).href,
       options.serverPath
@@ -92304,69 +92324,6 @@ async function launchInstrumented(options) {
   }
 }
 
-// src/trend.ts
-var DEFAULT_MIN_GROWTH = 256 * 1024;
-var STEPWISE_MIN_GROWING_CYCLES = 2;
-var STEPWISE_MAX_DRAWDOWN_RATIO = 0.1;
-function maxDrawdown(samples) {
-  let peak = samples[1] ?? 0;
-  let worst = 0;
-  for (let i = 1; i < samples.length; i += 1) {
-    const value = samples[i] ?? 0;
-    peak = Math.max(peak, value);
-    worst = Math.max(worst, peak - value);
-  }
-  return worst;
-}
-function isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth) {
-  if (growingCycles < STEPWISE_MIN_GROWING_CYCLES || mean < minGrowth) {
-    return false;
-  }
-  const netGrowth = deltas.reduce((sum, delta) => sum + delta, 0);
-  if (netGrowth <= 0) {
-    return false;
-  }
-  return maxDrawdown(samples) <= netGrowth * STEPWISE_MAX_DRAWDOWN_RATIO;
-}
-function classifyTrend(samples, options = {}) {
-  const minGrowth = options.minGrowthPerCycle ?? DEFAULT_MIN_GROWTH;
-  if (samples.length < 4) {
-    return { verdict: "inconclusive", growthPerCycle: 0, deltas: [] };
-  }
-  const deltas = [];
-  for (let i = 2; i < samples.length; i += 1) {
-    const current = samples[i];
-    const previous = samples[i - 1];
-    if (current === void 0 || previous === void 0) {
-      return { verdict: "inconclusive", growthPerCycle: 0, deltas: [] };
-    }
-    deltas.push(current - previous);
-  }
-  const mean = deltas.reduce((sum, d) => sum + d, 0) / deltas.length;
-  const allGrow = deltas.every((d) => d >= minGrowth);
-  const anyFlatOrDown = deltas.some((d) => d <= 0);
-  const growingCycles = deltas.filter((d) => d >= minGrowth).length;
-  if (allGrow) {
-    return { verdict: "leak", growthPerCycle: mean, deltas, source: "heap" };
-  }
-  if (isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth)) {
-    return { verdict: "leak", growthPerCycle: mean, deltas, source: "heap" };
-  }
-  if (anyFlatOrDown || mean < minGrowth) {
-    return { verdict: "stable", growthPerCycle: mean, deltas, source: "heap" };
-  }
-  return { verdict: "inconclusive", growthPerCycle: mean, deltas, source: "heap" };
-}
-function classifyMemoryTrend(heapSamples, externalSamples, options = {}) {
-  const heap = classifyTrend(heapSamples, options);
-  const external = classifyTrend(externalSamples, options);
-  const severity = { leak: 0, inconclusive: 1, stable: 2 };
-  if (severity[external.verdict] < severity[heap.verdict]) {
-    return { ...external, source: "external" };
-  }
-  return heap;
-}
-
 // src/report.ts
 var MB = 1024 * 1024;
 var formatMb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
@@ -92475,8 +92432,10 @@ function formatReport(report) {
   for (const route of report.routes) {
     lines.push(...routeLines(route));
   }
+  const { minGrowthPerCycle, loadRequests, cycles, maxOldSpaceMb } = report.parameters;
   lines.push(
     "",
+    `judged over ${cycles} cycles \xD7 ${loadRequests} requests, growth gate ${(minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle (${formatGrowth(minGrowthPerCycle / loadRequests * 1e3)}), heap cap ${maxOldSpaceMb} MB`,
     `snapshots and run.json: ${report.workDir}`,
     `report: ${report.bundle.htmlReport}`,
     ...report.bundle.issues.map((issue) => `issue draft (${issue.route}): ${issue.file}`)
@@ -93382,7 +93341,7 @@ var RITUAL_DEFAULTS = {
   warmupRequests: 200,
   loadRequests: 5e3,
   connections: 100,
-  cycles: 3,
+  cycles: 4,
   idleMs: 3e4
 };
 async function runRitual(options, deps = defaultDeps) {
@@ -93395,24 +93354,20 @@ async function runRitual(options, deps = defaultDeps) {
     throw new Error("the trend verdict needs at least 3 cycles");
   }
   await mkdir(options.workDir, { recursive: true });
+  const launchOptions = {
+    serverPath: options.serverPath,
+    workDir: options.workDir,
+    bootstrapPath: options.bootstrapPath,
+    ...options.maxOldSpaceMb !== void 0 && { maxOldSpaceMb: options.maxOldSpaceMb }
+  };
   let app;
   try {
-    app = await deps.launch({
-      serverPath: options.serverPath,
-      workDir: options.workDir,
-      appPort: options.appPort,
-      bootstrapPath: options.bootstrapPath
-    });
+    app = await deps.launch({ ...launchOptions, appPort: options.appPort });
   } catch (cause) {
     if (!String(cause).includes("EADDRINUSE")) {
       throw cause;
     }
-    app = await deps.launch({
-      serverPath: options.serverPath,
-      workDir: options.workDir,
-      appPort: options.appPort + 1,
-      bootstrapPath: options.bootstrapPath
-    });
+    app = await deps.launch({ ...launchOptions, appPort: options.appPort + 1 });
   }
   const timings = [];
   const loadOutcomes = [];
@@ -93497,6 +93452,7 @@ async function runRitual(options, deps = defaultDeps) {
     }
     const samples = memorySamples.map((sample) => sample.heapUsed);
     const externalSamples = memorySamples.map((sample) => sample.external);
+    const minGrowthPerCycle = minGrowthFor(loadRequests);
     return {
       route: options.route,
       timings,
@@ -93506,8 +93462,9 @@ async function runRitual(options, deps = defaultDeps) {
       memorySamples,
       baselineSnapshot: baseline.file,
       afterSnapshot,
-      trend: classifyMemoryTrend(samples, externalSamples),
-      requestsPerCycle: loadRequests
+      trend: classifyMemoryTrend(samples, externalSamples, { minGrowthPerCycle }),
+      requestsPerCycle: loadRequests,
+      minGrowthPerCycle
     };
   } finally {
     await app.close();
@@ -93806,6 +93763,7 @@ async function measureRoute(context, route, requestPath, index) {
     ...options.connections !== void 0 && { connections: options.connections },
     ...options.cycles !== void 0 && { cycles: options.cycles },
     ...options.idleMs !== void 0 && { idleMs: options.idleMs },
+    ...options.maxOldSpaceMb !== void 0 && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...routeConfig.headers !== void 0 && { headers: routeConfig.headers },
     ...routeConfig.abandonAfterMs !== void 0 && {
       abandonAfterMs: routeConfig.abandonAfterMs
@@ -93815,6 +93773,11 @@ async function measureRoute(context, route, requestPath, index) {
     trend: result.trend,
     loadOutcomes: result.loadOutcomes,
     settleOutcomes: result.settleOutcomes,
+    // The audit has to grade against the gate the verdict actually used, or
+    // the noise-floor warning describes a threshold nobody applied.
+    minGrowthPerCycle: result.minGrowthPerCycle,
+    memorySamples: result.memorySamples,
+    maxOldSpaceMb: options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB,
     ...routeConfig.abandonAfterMs !== void 0 && {
       abandonAfterMs: routeConfig.abandonAfterMs
     }
@@ -93849,8 +93812,8 @@ async function measureRoute(context, route, requestPath, index) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-26DU7JFW.js");
-  const { renderIssueMarkdown } = await import("./issue-report-FUTEOHN5.js");
+  const { renderHtmlReport } = await import("./html-report-2SOTNXDG.js");
+  const { renderIssueMarkdown } = await import("./issue-report-X5JYAVN5.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
       const file = path6.join(workDir, `ISSUE-${routeSlug(route.route)}.md`);
@@ -93892,12 +93855,15 @@ async function planRun(options, target, deps, progress) {
   progress(
     `module registry: ${registry.size} modules` + (nextVersion === null ? "" : ` \xB7 next ${nextVersion}`)
   );
+  const loadRequests = options.loadRequests ?? RITUAL_DEFAULTS.loadRequests;
   const parameters = {
     warmupRequests: options.warmupRequests ?? RITUAL_DEFAULTS.warmupRequests,
-    loadRequests: options.loadRequests ?? RITUAL_DEFAULTS.loadRequests,
+    loadRequests,
     connections: options.connections ?? RITUAL_DEFAULTS.connections,
     cycles: options.cycles ?? RITUAL_DEFAULTS.cycles,
-    idleMs: options.idleMs ?? RITUAL_DEFAULTS.idleMs
+    idleMs: options.idleMs ?? RITUAL_DEFAULTS.idleMs,
+    maxOldSpaceMb: options.maxOldSpaceMb ?? DEFAULT_MAX_OLD_SPACE_MB,
+    minGrowthPerCycle: minGrowthFor(loadRequests)
   };
   const measurable = routes.filter(
     (route) => skipReason(route, resolveRoutePath(route.path, routeConfig)) === null
@@ -93972,7 +93938,6 @@ export {
   LaunchError,
   killActiveChildren,
   launchInstrumented,
-  classifyTrend,
   formatReport,
   RouteConfigError,
   ROUTE_CONFIG_FILE,

package/dist/{chunk-5ZYZW2BL.js → chunk-MYYPTZJW.js}

@@ -60,7 +60,7 @@ OS: ${environment.platform} ${environment.arch}${environment.cpuModel ? ` (${env
 Memory: ${(environment.totalMemoryBytes / (1024 * MB)).toFixed(0)} GB
 Next.js: ${environment.nextVersion ?? "unknown"}
 next-leak: ${environment.nextLeakVersion}
-Deployment: output "standalone", node --expose-gc --max-old-space-size=512
+Deployment: output "standalone", node --expose-gc --max-old-space-size=${parameters.maxOldSpaceMb}
 \`\`\`
 
 ### To Reproduce
@@ -72,6 +72,8 @@ Deployment: output "standalone", node --expose-gc --max-old-space-size=512
 2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against \`${route.requestPath}\`:
    warm-up ${parameters.warmupRequests} requests \u2192 forced GC \u2192 baseline heap snapshot \u2192
    ${parameters.cycles} \xD7 [${parameters.loadRequests} requests at ${parameters.connections} connections \u2192 ${(parameters.idleMs / 1e3).toFixed(0)}s idle \u2192 forced GC \u2192 post-GC sample] \u2192 final snapshot.
+3. A cycle counts as growing when it retains at least ${(parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB
+   (the gate for this run's ${parameters.loadRequests} requests per cycle); the warm-up cycle is excluded.
 
 ### Current vs. Expected behavior
 

package/dist/{chunk-C3KH5Z2W.js → chunk-SKAPGI62.js}

@@ -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 {
   effectiveVerdict
-} from "./chunk-2BQZCZ4Z.js";
+} from "./chunk-E5ZKAANQ.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
@@ -77,6 +77,7 @@ code{background:#f4f4f4;padding:0 4px;border-radius:3px}
   )} \xB7 ${escapeHtml(environment.platform)}/${escapeHtml(environment.arch)} \xB7 next ${escapeHtml(
     environment.nextVersion ?? "unknown"
   )} \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(measuredSection).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>`}

package/dist/cli-args.d.ts

@@ -5,6 +5,7 @@ export type CliRunOptions = {
     requests: number | null;
     connections: number | null;
     idleSeconds: number | null;
+    maxOldSpaceMb: number | null;
     quick: boolean;
     diffAll: boolean;
     output: string | null;

package/dist/cli.js

@@ -9,8 +9,8 @@ import {
   killActiveChildren,
   parseCliArgs,
   runMeasurement
-} from "./chunk-ZFYIR423.js";
-import "./chunk-2BQZCZ4Z.js";
+} from "./chunk-HAKKAIHN.js";
+import "./chunk-E5ZKAANQ.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
@@ -97,6 +97,7 @@ async function main() {
     ...options.requests !== null && { loadRequests: options.requests },
     ...options.connections !== null && { connections: options.connections },
     ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
+    ...options.maxOldSpaceMb !== null && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...options.diffAll && { diffAll: true },
     ...options.output !== null && { outputDir: options.output },
     onProgress: (message) => console.error(`\xB7 ${message}`)

package/dist/confidence.d.ts

@@ -1,5 +1,6 @@
+import type { HeapSample } from "./control-server.js";
 import type { LoadOutcome, SettleOutcome } from "./ritual.js";
-import type { TrendResult, TrendVerdict } from "./trend.js";
+import { type TrendResult, type TrendVerdict } from "./trend.js";
 /**
  * Why a measurement may not support its own verdict.
  *
@@ -11,8 +12,10 @@ import type { TrendResult, TrendVerdict } from "./trend.js";
  *   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
+ * `near-heap-ceiling`   — the heap approached the cap the process ran under,
+ *   so the curve was measured against a ceiling instead of running free
  */
-export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold";
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "near-heap-ceiling";
 export type MeasurementWarning = {
     code: WarningCode;
     detail: string;
@@ -36,6 +39,10 @@ export type ConfidenceInput = {
     abandonAfterMs?: number;
     /** Threshold the verdict used, for the noise-floor check. */
     minGrowthPerCycle?: number;
+    /** Post-GC samples, for the heap-ceiling check. */
+    memorySamples?: readonly HeapSample[];
+    /** Old-space cap the measured process ran under (MB). */
+    maxOldSpaceMb?: number;
 };
 /**
  * The verdict a route's evidence actually supports.

package/dist/{html-report-26DU7JFW.js → html-report-2SOTNXDG.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 {
   renderHtmlReport
-} from "./chunk-C3KH5Z2W.js";
-import "./chunk-2BQZCZ4Z.js";
+} from "./chunk-SKAPGI62.js";
+import "./chunk-E5ZKAANQ.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderHtmlReport

package/dist/index.js

@@ -13,7 +13,6 @@ import {
   captureEnvironment,
   checkRuntime,
   classifySource,
-  classifyTrend,
   decodeMappings,
   decodeVlqLine,
   diffAgainstBaseline,
@@ -40,14 +39,16 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-ZFYIR423.js";
+} from "./chunk-HAKKAIHN.js";
 import {
   renderHtmlReport
-} from "./chunk-C3KH5Z2W.js";
-import "./chunk-2BQZCZ4Z.js";
+} from "./chunk-SKAPGI62.js";
+import {
+  classifyTrend
+} from "./chunk-E5ZKAANQ.js";
 import {
   renderIssueMarkdown
-} from "./chunk-5ZYZW2BL.js";
+} from "./chunk-MYYPTZJW.js";
 import "./chunk-6XYFBOL2.js";
 export {
   LaunchError,

package/dist/{issue-report-FUTEOHN5.js → issue-report-X5JYAVN5.js}

@@ -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 {
   renderIssueMarkdown
-} from "./chunk-5ZYZW2BL.js";
+} from "./chunk-MYYPTZJW.js";
 import "./chunk-6XYFBOL2.js";
 export {
   renderIssueMarkdown

package/dist/launcher.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Old-space cap for measured processes, when the caller does not pick one.
+ *
+ * Small on purpose: a leak that would take a production container an hour to
+ * kill reaches a 512 MB ceiling in minutes. It is a default, not a constant —
+ * an app whose legitimate working set is larger cannot be measured under it,
+ * so `--max-old-space` exists and the chosen value is recorded in `run.json`.
+ */
+export declare const DEFAULT_MAX_OLD_SPACE_MB = 512;
 export type LaunchOptions = {
     /** Absolute path to the standalone `server.js` (or any PORT/HOSTNAME-honoring server). */
     serverPath: string;

package/dist/ritual.d.ts

@@ -17,6 +17,8 @@ export type RitualOptions = {
     connections?: number;
     cycles?: number;
     idleMs?: number;
+    /** Old-space cap for the measured process (MB). Default: 512. */
+    maxOldSpaceMb?: number;
     /** Headers sent with every request during warm-up and load. */
     headers?: Record<string, string>;
     /** Emulate clients that disconnect before the response arrives. */
@@ -68,6 +70,12 @@ export type RitualResult = {
     afterSnapshot: string;
     trend: TrendResult;
     requestsPerCycle: number;
+    /**
+     * The gate (bytes per cycle) this verdict was judged against. Travels with
+     * the result so the confidence audit grades against the same number the
+     * verdict used, and so the report can print what it measured against.
+     */
+    minGrowthPerCycle: number;
 };
 /** Injectable seams for unit tests; production uses the real implementations. */
 export type RitualDeps = {
@@ -75,12 +83,23 @@ export type RitualDeps = {
     load: typeof runLoadPhase;
     sleep: (ms: number) => Promise<void>;
 };
-/** Single source of truth for ritual defaults — reports must echo them. */
+/**
+ * Single source of truth for ritual defaults — reports must echo them.
+ *
+ * `cycles` is 4 rather than the minimum 3 because of how much the verdict
+ * actually sees: the sample array is `[baseline, ...cycles]` and
+ * `classifyTrend` drops the warm-up delta, leaving `cycles - 1` numbers. At 3
+ * cycles that is **two** deltas, and `anyFlatOrDown` needs only one of the two
+ * to be non-positive to call a route stable — one noisy cycle flips the
+ * verdict. Four cycles give three deltas, which is what the real-app
+ * validation ran with. The 3-cycle minimum stays available for users who want
+ * a faster, weaker read.
+ */
 export declare const RITUAL_DEFAULTS: {
     readonly warmupRequests: 200;
     readonly loadRequests: 5000;
     readonly connections: 100;
-    readonly cycles: 3;
+    readonly cycles: 4;
     readonly idleMs: 30000;
 };
 /**

package/dist/runner.d.ts

@@ -6,7 +6,7 @@ import { diffSnapshotFiles, type HeapDiff } from "./heap-diff.js";
 import { extractModuleRegistry } from "./module-registry.js";
 import { runRitual, type LoadOutcome, type PhaseTiming, type SettleOutcome } from "./ritual.js";
 import { readNextVersion, type MatchedSignature } from "./signatures.js";
-import type { TrendResult } from "./trend.js";
+import { type TrendResult } from "./trend.js";
 export type RouteReport = {
     route: string;
     status: "skipped";
@@ -61,6 +61,18 @@ export type RunParameters = {
     connections: number;
     cycles: number;
     idleMs: number;
+    /**
+     * Old-space cap of each measured process (MB). Part of the measurement
+     * regime: a run near its ceiling is not the same experiment as one with
+     * headroom, so it belongs on the record.
+     */
+    maxOldSpaceMb: number;
+    /**
+     * Per-cycle growth gate the verdicts were judged against (bytes). Derived
+     * from `loadRequests`; recorded because a verdict whose threshold is not
+     * printed cannot be audited or reproduced.
+     */
+    minGrowthPerCycle: number;
 };
 export type RunReport = {
     appDir: string;
@@ -88,6 +100,8 @@ export type RunOptions = {
     connections?: number;
     cycles?: number;
     idleMs?: number;
+    /** Old-space cap for each measured process (MB). Default 512. */
+    maxOldSpaceMb?: number;
     /** Also diff routes with a stable verdict. Default false: diffs are slow. */
     diffAll?: boolean;
     /** Only measure routes matching these templates or prefixes. */