@cad0p/pi-memory-budget 0.0.0-stage → 0.1.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.
package/src/runner.mjs ADDED
@@ -0,0 +1,347 @@
1
+ // Spawns pi in RPC mode, samples its RSS and pings it, and cleans up.
2
+
3
+ import { spawn } from "node:child_process";
4
+ import { buildPiArgs } from "./pi.mjs";
5
+ import { readRss } from "./sampler.mjs";
6
+ import { summarize } from "./stats.mjs";
7
+
8
+ /** @type {Set<import("node:child_process").ChildProcess>} */
9
+ const live = new Set();
10
+ let hooksInstalled = false;
11
+
12
+ /** @param {import("node:child_process").ChildProcess} child @param {NodeJS.Signals} sig */
13
+ function killGroup(child, sig) {
14
+ if (child.pid === undefined) return;
15
+ try {
16
+ process.kill(-child.pid, sig); // pi is spawned detached: its own process group
17
+ } catch {
18
+ try {
19
+ child.kill(sig);
20
+ } catch {
21
+ // already gone
22
+ }
23
+ }
24
+ }
25
+
26
+ /** Kills every pi process still alive. Safe to call repeatedly. */
27
+ export function killAll() {
28
+ for (const c of live) killGroup(c, "SIGKILL");
29
+ }
30
+
31
+ /** Installs exit and signal hooks once, so no pi process is orphaned. */
32
+ export function installCleanupHooks() {
33
+ if (hooksInstalled) return;
34
+ hooksInstalled = true;
35
+ process.on("exit", killAll);
36
+ for (const sig of /** @type {const} */ (["SIGINT", "SIGTERM", "SIGHUP"])) {
37
+ process.on(sig, () => {
38
+ killAll();
39
+ process.exit(sig === "SIGINT" ? 130 : 143);
40
+ });
41
+ }
42
+ }
43
+
44
+ /** Env that keeps pi off the network, set for every configuration alike. */
45
+ export const PI_QUIET_ENV = Object.freeze({
46
+ PI_OFFLINE: "1",
47
+ PI_SKIP_VERSION_CHECK: "1",
48
+ PI_TELEMETRY: "0",
49
+ });
50
+
51
+ /**
52
+ * Last "pmb-gc: diag {json}" line the harness wrote (post-GC heap numbers).
53
+ * @param {string} stderr
54
+ */
55
+ export function parseGcDiag(stderr) {
56
+ const all = [...stderr.matchAll(/pmb-gc: diag (\{[^\n]*\})/g)];
57
+ if (!all.length) return null;
58
+ try {
59
+ const d = JSON.parse(all[all.length - 1][1]);
60
+ return {
61
+ heapUsedMb: d.heapUsed / 1048576,
62
+ externalMb: d.external / 1048576,
63
+ arrayBuffersMb: d.arrayBuffers / 1048576,
64
+ };
65
+ } catch {
66
+ return null;
67
+ }
68
+ }
69
+
70
+ /** @param {number} ms */
71
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
72
+
73
+ /** Cap on how far past --window a run extends to make a pending release observable. */
74
+ export const RELEASE_EXTEND_CAP_SEC = 60;
75
+
76
+ /** Total-RSS range (MB) under which a steady window counts as quiet. */
77
+ const SETTLE_RANGE_MB = 5;
78
+
79
+ /**
80
+ * @typedef {object} MeasureSpec
81
+ * @property {{ command: string, args: string[] }} pi
82
+ * @property {string[]} extensions
83
+ * @property {string[]} [harnessExtensions] extensions loaded in every configuration alike (GC harness)
84
+ * @property {boolean} [gc] start pi with --expose-gc via NODE_OPTIONS and load the GC harness (default true)
85
+ * @property {string | null} sessionFile
86
+ * @property {string} cwd
87
+ * @property {NodeJS.ProcessEnv} env
88
+ * @property {number} windowSec minimum sampling window
89
+ * @property {number} steadySec settled-window length for steady RSS
90
+ * @property {number} [settleMaxSec] cap on the quiescence wait (default 120)
91
+ * @property {number} [settleMinSec] no settle before this (default 0 here, 30 from the CLI)
92
+ * @property {number} [releaseSec] keep sampling until peak + this (bounded) so a release is observable
93
+ * @property {string[]} [extraArgs]
94
+ * @property {number} [sampleMs]
95
+ * @property {number} [pingMs]
96
+ */
97
+
98
+ /**
99
+ * @typedef {import("./stats.mjs").RunSummary & {
100
+ * samples: import("./stats.mjs").Sample[],
101
+ * maxGapMs: number,
102
+ * readyMs: number | null,
103
+ * pings: number,
104
+ * stderrTail: string,
105
+ * exitT: number | null,
106
+ * windowEndSec: number,
107
+ * gcReady: boolean | null,
108
+ * gcDiag: { heapUsedMb: number, externalMb: number, arrayBuffersMb: number } | null,
109
+ * }} RunResult
110
+ */
111
+
112
+ /**
113
+ * Runs one pi process for the window and measures it.
114
+ * @param {MeasureSpec} spec
115
+ * @returns {Promise<RunResult>}
116
+ */
117
+ export async function measureRun(spec) {
118
+ installCleanupHooks();
119
+ const sampleMs = spec.sampleMs ?? 200;
120
+ const pingMs = spec.pingMs ?? 100;
121
+ const settleMaxSec = spec.settleMaxSec ?? 120;
122
+ const settleMinSec = spec.settleMinSec ?? 0;
123
+ const releaseSec = spec.releaseSec ?? 0;
124
+ const useGc = spec.gc !== false;
125
+ const args = [
126
+ ...spec.pi.args,
127
+ ...buildPiArgs({
128
+ extensions: spec.extensions,
129
+ harnessExtensions: useGc ? spec.harnessExtensions : undefined,
130
+ sessionFile: spec.sessionFile,
131
+ extraArgs: spec.extraArgs,
132
+ }),
133
+ ];
134
+ // --expose-gc through NODE_OPTIONS reaches the node runtime whichever way pi
135
+ // is launched: a global shell-script launcher, a node_modules/.bin shim, or
136
+ // a plain "node cli.js" --pi value. gc() only ever runs inside the pi pid;
137
+ // children are measured as before.
138
+ // pi's startup network work (model catalog refresh, version check, telemetry)
139
+ // allocates ~40 MB at an unpredictable time and made vanilla settle at 120,
140
+ // 150 or 178 MB. Switched off identically for every config; spec.env wins.
141
+ const base = { ...PI_QUIET_ENV, ...spec.env };
142
+ const env = useGc
143
+ ? {
144
+ ...base,
145
+ NODE_OPTIONS: [spec.env?.NODE_OPTIONS, "--expose-gc"]
146
+ .filter(Boolean)
147
+ .join(" "),
148
+ }
149
+ : base;
150
+ const child = spawn(spec.pi.command, args, {
151
+ cwd: spec.cwd,
152
+ env,
153
+ stdio: ["pipe", "pipe", "pipe"],
154
+ detached: true,
155
+ });
156
+ live.add(child);
157
+ const t0 = performance.now();
158
+ let exited = false;
159
+ /** @type {number | null} */
160
+ let exitT = null;
161
+ /** @type {{ code: number | null, signal: string | null } | null} */
162
+ let exitInfo = null;
163
+ child.on("exit", (code, signal) => {
164
+ exited = true;
165
+ exitT = (performance.now() - t0) / 1000;
166
+ exitInfo = { code, signal };
167
+ });
168
+ /** @type {Error | null} */
169
+ let spawnError = null;
170
+ child.on("error", (e) => {
171
+ spawnError = e;
172
+ exited = true;
173
+ exitT = (performance.now() - t0) / 1000;
174
+ });
175
+ child.stdin?.on("error", () => {});
176
+ let stderrTail = "";
177
+ child.stderr?.on("data", (d) => {
178
+ stderrTail = (stderrTail + d).slice(-4000);
179
+ });
180
+
181
+ /** @type {Map<string, number>} */
182
+ const pending = new Map();
183
+ let seq = 0;
184
+ let maxGap = 0;
185
+ let pings = 0;
186
+ /** @type {number | null} */
187
+ let readyMs = null;
188
+ let buf = "";
189
+ child.stdout?.on("data", (d) => {
190
+ buf += d;
191
+ let i = buf.indexOf("\n");
192
+ while (i >= 0) {
193
+ const line = buf.slice(0, i);
194
+ buf = buf.slice(i + 1);
195
+ i = buf.indexOf("\n");
196
+ if (!line.includes('"response"')) continue;
197
+ try {
198
+ const m = JSON.parse(line);
199
+ const sent = m.type === "response" ? pending.get(m.id) : undefined;
200
+ if (sent !== undefined) {
201
+ pending.delete(m.id);
202
+ const now = performance.now();
203
+ maxGap = Math.max(maxGap, now - sent);
204
+ pings++;
205
+ if (readyMs === null) readyMs = now - t0;
206
+ }
207
+ } catch {
208
+ // not JSON: ignore
209
+ }
210
+ }
211
+ });
212
+
213
+ const pinger = setInterval(() => {
214
+ if (exited) return;
215
+ const id = `pmb-${++seq}`;
216
+ pending.set(id, performance.now());
217
+ child.stdin?.write(`${JSON.stringify({ id, type: "get_state" })}\n`);
218
+ }, pingMs);
219
+
220
+ /** @type {import("./stats.mjs").Sample[]} */
221
+ const samples = [];
222
+ try {
223
+ // The loop extends past windowSec when needed: until the peak's release is
224
+ // observable (peak + releaseSec), capped.
225
+ while (true) {
226
+ const now = performance.now();
227
+ if (spawnError) throw spawnError;
228
+ if (exited && samples.length === 0) break;
229
+ if (exited) {
230
+ // Died before the steady window is covered: hard error. During the
231
+ // release-observation extension: measurement cut short, exitT < end.
232
+ if ((now - t0) / 1000 < spec.windowSec) {
233
+ throw new Error(
234
+ `pi exited after ${(exitT ?? 0).toFixed(1)}s, before the ${spec.windowSec}s window ended ${JSON.stringify(exitInfo)}\n${stderrTail}`,
235
+ );
236
+ }
237
+ break;
238
+ }
239
+ const r = await readRss(/** @type {number} */ (child.pid));
240
+ if (r.rssMb !== null) {
241
+ samples.push({
242
+ t: (performance.now() - t0) / 1000,
243
+ rss: r.rssMb,
244
+ main: r.mainMb ?? 0,
245
+ kids: r.kidsMb,
246
+ });
247
+ }
248
+ const lastT = (performance.now() - t0) / 1000;
249
+ if (lastT < spec.windowSec) {
250
+ await sleep(Math.max(0, sampleMs - (performance.now() - now)));
251
+ continue;
252
+ }
253
+ // Past the minimum window: two reasons to keep sampling.
254
+ // (a) Quiescence: the process has not been quiet for a full steady
255
+ // window yet (and the run must not stop right before it would settle).
256
+ let quiet = samples.length > 0;
257
+ if (quiet) {
258
+ const last = samples[samples.length - 1];
259
+ if (last.t < spec.steadySec) quiet = false;
260
+ else {
261
+ let lo = Number.POSITIVE_INFINITY;
262
+ let hi = Number.NEGATIVE_INFINITY;
263
+ for (let k = samples.length - 1; k >= 0; k--) {
264
+ const s = samples[k];
265
+ if (last.t - s.t > spec.steadySec) break;
266
+ if (s.rss < lo) lo = s.rss;
267
+ if (s.rss > hi) hi = s.rss;
268
+ }
269
+ quiet = hi - lo < SETTLE_RANGE_MB;
270
+ }
271
+ }
272
+ const waitForSettle =
273
+ (!quiet || lastT < settleMinSec) && lastT < settleMaxSec;
274
+ // (b) Release not yet observable AND RSS still at the peak: keep sampling
275
+ // so the check never has to fail on an unobserved release.
276
+ let waitForRelease = false;
277
+ if (releaseSec > 0 && samples.length) {
278
+ const peak = samples.reduce((a, b) => (b.rss > a.rss ? b : a));
279
+ waitForRelease =
280
+ samples[samples.length - 1].rss >= peak.rss - 0.5 &&
281
+ lastT < peak.t + releaseSec &&
282
+ lastT < spec.windowSec + RELEASE_EXTEND_CAP_SEC;
283
+ }
284
+ if (!waitForSettle && !waitForRelease) break;
285
+ await sleep(Math.max(0, sampleMs - (performance.now() - now)));
286
+ }
287
+ if (spawnError) throw spawnError;
288
+ if (samples.length === 0) {
289
+ throw new Error(`pi produced no RSS samples: ${stderrTail}`);
290
+ }
291
+ for (const sent of pending.values())
292
+ maxGap = Math.max(maxGap, performance.now() - sent);
293
+ return {
294
+ ...summarize(samples, {
295
+ settleMax: settleMaxSec,
296
+ quietSec: spec.steadySec,
297
+ settleMin: settleMinSec,
298
+ }),
299
+ samples,
300
+ maxGapMs: maxGap,
301
+ readyMs,
302
+ pings,
303
+ stderrTail,
304
+ exitT,
305
+ windowEndSec: samples[samples.length - 1].t,
306
+ gcDiag: parseGcDiag(stderrTail),
307
+ gcReady: !useGc
308
+ ? null
309
+ : spec.harnessExtensions?.length
310
+ ? /pmb-gc: ready/.test(stderrTail)
311
+ : null,
312
+ };
313
+ } finally {
314
+ clearInterval(pinger);
315
+ await stop(child);
316
+ }
317
+ }
318
+
319
+ /** @param {import("node:child_process").ChildProcess} child */
320
+ async function stop(child) {
321
+ try {
322
+ child.stdin?.end();
323
+ } catch {
324
+ // ignore
325
+ }
326
+ killGroup(child, "SIGTERM");
327
+ const deadline = Date.now() + 5000;
328
+ while (
329
+ child.exitCode === null &&
330
+ child.signalCode === null &&
331
+ Date.now() < deadline
332
+ )
333
+ await sleep(50);
334
+ if (child.exitCode === null && child.signalCode === null) {
335
+ killGroup(child, "SIGKILL");
336
+ const d2 = Date.now() + 3000;
337
+ while (
338
+ child.exitCode === null &&
339
+ child.signalCode === null &&
340
+ Date.now() < d2
341
+ )
342
+ await sleep(50);
343
+ }
344
+ // also take down any straggler in the group (extension child processes)
345
+ killGroup(child, "SIGKILL");
346
+ live.delete(child);
347
+ }
@@ -0,0 +1,162 @@
1
+ // RSS sampling of a process and its descendants (recursive).
2
+ // Linux: /proc/<pid>/status VmRSS plus /proc/<pid>/task/*/children for the
3
+ // descendant walk (cheap: only the subtree, not all of /proc). macOS: ps.
4
+
5
+ import { execFile } from "node:child_process";
6
+ import fs from "node:fs";
7
+
8
+ const KB_PER_MB = 1024;
9
+
10
+ /**
11
+ * @param {string} text contents of /proc/<pid>/status
12
+ * @returns {number | null} VmRSS in KB
13
+ */
14
+ export function parseVmRss(text) {
15
+ const m = /^VmRSS:\s+(\d+)\s*kB/m.exec(text);
16
+ return m ? Number(m[1]) : null;
17
+ }
18
+
19
+ /**
20
+ * @param {string} text output of `ps -A -o pid=,ppid=,rss=`
21
+ * @returns {{ pid: number, ppid: number, rssKb: number }[]}
22
+ */
23
+ export function parsePsTable(text) {
24
+ /** @type {{ pid: number, ppid: number, rssKb: number }[]} */
25
+ const rows = [];
26
+ for (const line of text.split("\n")) {
27
+ const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s*$/.exec(line);
28
+ if (m)
29
+ rows.push({ pid: Number(m[1]), ppid: Number(m[2]), rssKb: Number(m[3]) });
30
+ }
31
+ return rows;
32
+ }
33
+
34
+ /**
35
+ * Sum of RSS (KB) of all descendants of root in a process table.
36
+ * @param {{ pid: number, ppid: number, rssKb: number }[]} rows
37
+ * @param {number} root
38
+ */
39
+ export function descendantsRssKb(rows, root) {
40
+ /** @type {Map<number, number[]>} */
41
+ const kids = new Map();
42
+ for (const r of rows) {
43
+ const list = kids.get(r.ppid);
44
+ if (list) list.push(r.pid);
45
+ else kids.set(r.ppid, [r.pid]);
46
+ }
47
+ const rss = new Map(rows.map((r) => [r.pid, r.rssKb]));
48
+ let total = 0;
49
+ const stack = [...(kids.get(root) ?? [])];
50
+ const seen = new Set();
51
+ while (stack.length) {
52
+ const pid = /** @type {number} */ (stack.pop());
53
+ if (seen.has(pid)) continue;
54
+ seen.add(pid);
55
+ total += rss.get(pid) ?? 0;
56
+ stack.push(...(kids.get(pid) ?? []));
57
+ }
58
+ return total;
59
+ }
60
+
61
+ /** @param {number} pid @returns {number | null} VmRSS in KB */
62
+ function procRssKb(pid) {
63
+ try {
64
+ return parseVmRss(fs.readFileSync(`/proc/${pid}/status`, "utf8"));
65
+ } catch {
66
+ return null;
67
+ }
68
+ }
69
+
70
+ /**
71
+ * Pids of all descendants of pid, via /proc/<pid>/task/<tid>/children (each task
72
+ * lists the same child pids). BFS over the subtree only: cheap enough to run
73
+ * every sample tick without stalling the harness event loop.
74
+ * @param {number} pid
75
+ * @returns {Set<number>}
76
+ */
77
+ export function linuxDescendants(pid) {
78
+ /** @type {Set<number>} */
79
+ const out = new Set();
80
+ const queue = [pid];
81
+ /** @type {Set<number>} */
82
+ const seen = new Set([pid]);
83
+ while (queue.length) {
84
+ const p = /** @type {number} */ (queue.pop());
85
+ let tasks;
86
+ try {
87
+ tasks = fs.readdirSync(`/proc/${p}/task`);
88
+ } catch {
89
+ continue; // process gone
90
+ }
91
+ for (const t of tasks) {
92
+ let children;
93
+ try {
94
+ children = fs.readFileSync(`/proc/${p}/task/${t}/children`, "utf8");
95
+ } catch {
96
+ continue;
97
+ }
98
+ for (const c of children.trim().split(/\s+/)) {
99
+ const cp = Number(c);
100
+ if (cp > 0 && !seen.has(cp)) {
101
+ seen.add(cp);
102
+ out.add(cp);
103
+ queue.push(cp);
104
+ }
105
+ }
106
+ }
107
+ }
108
+ return out;
109
+ }
110
+
111
+ /** @param {string[]} args @returns {Promise<string>} */
112
+ function run(args) {
113
+ return new Promise((resolve) => {
114
+ execFile("ps", args, { encoding: "utf8" }, (err, stdout) =>
115
+ resolve(err ? "" : stdout),
116
+ );
117
+ });
118
+ }
119
+
120
+ /**
121
+ * Total RSS of pid plus all descendants, and the split for diagnosis.
122
+ * @param {number} pid
123
+ * @param {{ withChildren?: boolean }} [opts]
124
+ * @returns {Promise<{ rssMb: number | null, mainMb: number | null, kidsMb: number }>}
125
+ * rssMb null when the process is gone (kidsMb is still the last read: descendants may outlive it)
126
+ */
127
+ export async function readRss(pid, opts = {}) {
128
+ const withChildren = opts.withChildren ?? true;
129
+ if (process.platform === "linux") {
130
+ const mainKb = procRssKb(pid);
131
+ let kidsKb = 0;
132
+ if (withChildren) {
133
+ for (const d of linuxDescendants(pid)) kidsKb += procRssKb(d) ?? 0;
134
+ }
135
+ return {
136
+ rssMb:
137
+ mainKb === null
138
+ ? kidsKb > 0
139
+ ? kidsKb / KB_PER_MB
140
+ : null
141
+ : (mainKb + kidsKb) / KB_PER_MB,
142
+ mainMb: mainKb === null ? null : mainKb / KB_PER_MB,
143
+ kidsMb: kidsKb / KB_PER_MB,
144
+ };
145
+ }
146
+ // macOS / other unix: one ps call for the whole table (main row included).
147
+ const table = parsePsTable(await run(["-A", "-o", "pid=,ppid=,rss="]));
148
+ const self = table.find((r) => r.pid === pid);
149
+ const kidsKb = withChildren ? descendantsRssKb(table, pid) : 0;
150
+ if (!self)
151
+ return {
152
+ rssMb: kidsKb > 0 ? kidsKb / KB_PER_MB : null,
153
+ mainMb: null,
154
+ kidsMb: kidsKb / KB_PER_MB,
155
+ };
156
+ const kids = withChildren ? kidsKb : 0;
157
+ return {
158
+ rssMb: (self.rssKb + kids) / KB_PER_MB,
159
+ mainMb: self.rssKb / KB_PER_MB,
160
+ kidsMb: kids / KB_PER_MB,
161
+ };
162
+ }
package/src/stats.mjs ADDED
@@ -0,0 +1,163 @@
1
+ // Pure statistics helpers (no I/O).
2
+
3
+ /**
4
+ * @param {number[]} values
5
+ * @returns {number} median, NaN for an empty list (Infinity sorts last)
6
+ */
7
+ export function median(values) {
8
+ if (values.length === 0) return Number.NaN;
9
+ const s = [...values].sort((a, b) => a - b);
10
+ const mid = s.length >> 1;
11
+ const lo = s[mid - 1];
12
+ const hi = s[mid];
13
+ if (s.length % 2) return hi;
14
+ return lo === hi ? hi : (lo + hi) / 2;
15
+ }
16
+
17
+ /**
18
+ * @param {number[]} values
19
+ * @returns {number} max, -Infinity for an empty list
20
+ */
21
+ export function max(values) {
22
+ let m = Number.NEGATIVE_INFINITY;
23
+ for (const v of values) if (v > m) m = v;
24
+ return m;
25
+ }
26
+
27
+ /**
28
+ * One RSS sample. t is seconds since spawn. rss is the TOTAL memory of the pi
29
+ * process: main pid plus every descendant, in MB. main and kids split it for
30
+ * diagnosis.
31
+ * @typedef {{ t: number, rss: number, main: number, kids: number }} Sample
32
+ */
33
+
34
+ /**
35
+ * The first quiescent point: the earliest T, at least quietSec after spawn,
36
+ * whose trailing quietSec window has a total-RSS range under maxRangeMb and
37
+ * whose level then holds for the rest of the run. Settling late is a real
38
+ * signal (still-loading process, deferred work), so the caller caps it with
39
+ * settleMax.
40
+ * @param {Sample[]} samples
41
+ * @param {{ quietSec?: number, maxRangeMb?: number, settleMax?: number, settleMin?: number }} [o]
42
+ * @returns {{ settled: boolean, t: number | null, quietSec: number }}
43
+ */
44
+ export function findSettle(samples, o = {}) {
45
+ const quietSec = o.quietSec ?? 10;
46
+ const maxRangeMb = o.maxRangeMb ?? 5;
47
+ const settleMax = o.settleMax ?? Number.POSITIVE_INFINITY;
48
+ const settleMin = o.settleMin ?? 0; // no settle before this many seconds (late startup work)
49
+ const slack = 0.5;
50
+ // The settled point is the earliest T, at least quietSec after the start,
51
+ // where the last quietSec form a quiet window AND the whole suffix after T
52
+ // stays at that level. Requiring the suffix to hold is what keeps a flat
53
+ // spike plateau, a process that ramps again after T, or a still-loading
54
+ // process from counting as steady.
55
+ for (let i = 0; i < samples.length; i++) {
56
+ const T = samples[i].t;
57
+ if (T > settleMax) break;
58
+ if (T < settleMin) continue;
59
+ if (T - samples[0].t < quietSec - slack) continue; // window not long enough yet
60
+ if (i > 0 && T - samples[i - 1].t > 1) continue; // sampling gap: do not guess
61
+ let lo = Number.POSITIVE_INFINITY;
62
+ let hi = Number.NEGATIVE_INFINITY;
63
+ for (let j = i; j >= 0; j--) {
64
+ const s = samples[j];
65
+ if (T - s.t > quietSec) break;
66
+ if (s.rss < lo) lo = s.rss;
67
+ if (s.rss > hi) hi = s.rss;
68
+ }
69
+ if (!Number.isFinite(lo) || hi - lo >= maxRangeMb) continue;
70
+ let holds = true;
71
+ for (let j = i + 1; j < samples.length; j++) {
72
+ if (samples[j].rss > hi + slack || samples[j].rss < lo - slack) {
73
+ holds = false;
74
+ break;
75
+ }
76
+ }
77
+ if (holds) return { settled: true, t: T, quietSec };
78
+ }
79
+ return { settled: false, t: null, quietSec };
80
+ }
81
+
82
+ /**
83
+ * @typedef {object} RunSummary
84
+ * @property {boolean} settled whether quiescence was found before settleMax
85
+ * @property {number | null} settleT seconds since spawn at which the process settled
86
+ * @property {number | null} steadyMb median total RSS of the settled 10 s window; null when not settled
87
+ * @property {number} spikeMb max total RSS over the whole run
88
+ * @property {number | null} releasedMb total RSS of the last sample
89
+ * @property {number} peakT seconds since spawn at which the spike happened
90
+ * @property {number | null} mainSteadyMb median main-pid RSS of the settled window
91
+ * @property {number | null} childrenSteadyMb median descendant RSS of the settled window
92
+ * @property {number} childrenSpikeMb max descendant RSS
93
+ */
94
+
95
+ /**
96
+ * @param {Sample[]} samples
97
+ * @param {{ settleMax?: number, quietSec?: number, settleMin?: number }} [o]
98
+ * @returns {RunSummary}
99
+ */
100
+ export function summarize(samples, o = {}) {
101
+ if (samples.length === 0) throw new Error("no RSS samples collected");
102
+ const last = samples[samples.length - 1];
103
+ const settle = findSettle(samples, {
104
+ quietSec: o.quietSec,
105
+ settleMax: o.settleMax,
106
+ settleMin: o.settleMin,
107
+ });
108
+ let peak = samples[0];
109
+ for (const s of samples) if (s.rss > peak.rss) peak = s;
110
+ const tail =
111
+ settle.t === null
112
+ ? []
113
+ : samples.filter(
114
+ (s) => s.t >= /** @type {number} */ (settle.t) - settle.quietSec,
115
+ );
116
+ return {
117
+ settled: settle.settled,
118
+ settleT: settle.t,
119
+ steadyMb: tail.length ? median(tail.map((s) => s.rss)) : null,
120
+ spikeMb: peak.rss,
121
+ releasedMb: last.rss,
122
+ peakT: peak.t,
123
+ mainSteadyMb: tail.length ? median(tail.map((s) => s.main)) : null,
124
+ childrenSteadyMb: tail.length ? median(tail.map((s) => s.kids)) : null,
125
+ childrenSpikeMb: max(samples.map((s) => s.kids)),
126
+ };
127
+ }
128
+
129
+ /**
130
+ * Seconds from the RSS peak until the delta over the vanilla steady RSS first
131
+ * holds at or below the steady budget for `hold` consecutive samples (one dip
132
+ * does not count: RSS rebounds all the time). 0 when the peak itself is within
133
+ * the budget, null when it never releases within the samples.
134
+ * @param {Sample[]} samples
135
+ * @param {number} vanillaSteadyMb
136
+ * @param {number} steadyBudgetMb
137
+ * @param {number} [hold]
138
+ * @returns {number | null}
139
+ */
140
+ export function releaseSeconds(
141
+ samples,
142
+ vanillaSteadyMb,
143
+ steadyBudgetMb,
144
+ hold = 3,
145
+ ) {
146
+ if (samples.length === 0) return null;
147
+ let peakIdx = 0;
148
+ for (let i = 0; i < samples.length; i++) {
149
+ if (samples[i].rss > samples[peakIdx].rss) peakIdx = i;
150
+ }
151
+ const peak = samples[peakIdx];
152
+ if (peak.rss - vanillaSteadyMb <= steadyBudgetMb) return 0;
153
+ let streak = 0;
154
+ for (let i = peakIdx + 1; i < samples.length; i++) {
155
+ if (samples[i].rss - vanillaSteadyMb <= steadyBudgetMb) {
156
+ streak++;
157
+ if (streak >= hold) return samples[i - streak + 1].t - peak.t;
158
+ } else {
159
+ streak = 0;
160
+ }
161
+ }
162
+ return null;
163
+ }