@smoothbricks/nx-plugin 0.7.5 → 0.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +20 -3
  2. package/dist/.build-inputs.json +11 -5
  3. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts +3 -2
  4. package/dist/executors/bounded-exec/cpu-pool-thread.d.ts.map +1 -1
  5. package/dist/executors/bounded-exec/cpu-pool-thread.js +1 -1
  6. package/dist/executors/bounded-exec/cpu-pool.d.ts +24 -10
  7. package/dist/executors/bounded-exec/cpu-pool.d.ts.map +1 -1
  8. package/dist/executors/bounded-exec/cpu-pool.js +96 -52
  9. package/dist/executors/bounded-exec/executor.d.ts.map +1 -1
  10. package/dist/executors/bounded-exec/executor.js +98 -45
  11. package/dist/executors/bounded-exec/host-memory.d.ts +47 -0
  12. package/dist/executors/bounded-exec/host-memory.d.ts.map +1 -0
  13. package/dist/executors/bounded-exec/host-memory.darwin.d.ts +3 -0
  14. package/dist/executors/bounded-exec/host-memory.darwin.d.ts.map +1 -0
  15. package/dist/executors/bounded-exec/host-memory.darwin.js +40 -0
  16. package/dist/executors/bounded-exec/host-memory.js +29 -0
  17. package/dist/executors/bounded-exec/host-memory.linux.d.ts +14 -0
  18. package/dist/executors/bounded-exec/host-memory.linux.d.ts.map +1 -0
  19. package/dist/executors/bounded-exec/host-memory.linux.js +104 -0
  20. package/dist/executors/bounded-exec/leaf-peak.d.ts +55 -0
  21. package/dist/executors/bounded-exec/leaf-peak.d.ts.map +1 -0
  22. package/dist/executors/bounded-exec/leaf-peak.js +146 -0
  23. package/dist/executors/bounded-exec/peak-waiter.d.ts +2 -0
  24. package/dist/executors/bounded-exec/peak-waiter.d.ts.map +1 -0
  25. package/dist/executors/bounded-exec/peak-waiter.js +53 -0
  26. package/dist/executors/bounded-exec/pool-admission.d.ts +38 -0
  27. package/dist/executors/bounded-exec/pool-admission.d.ts.map +1 -0
  28. package/dist/executors/bounded-exec/pool-admission.js +31 -0
  29. package/dist/executors/bounded-exec/run-cpu-pool.d.ts +6 -4
  30. package/dist/executors/bounded-exec/run-cpu-pool.d.ts.map +1 -1
  31. package/dist/executors/bounded-exec/run-cpu-pool.js +20 -7
  32. package/dist/executors/bounded-exec/verdict.d.ts +18 -0
  33. package/dist/executors/bounded-exec/verdict.d.ts.map +1 -1
  34. package/dist/executors/bounded-exec/verdict.js +21 -1
  35. package/package.json +1 -1
  36. package/src/executors/bounded-exec/cpu-pool-thread.ts +4 -3
  37. package/src/executors/bounded-exec/cpu-pool.ts +111 -49
  38. package/src/executors/bounded-exec/executor.ts +103 -41
  39. package/src/executors/bounded-exec/host-memory.darwin.ts +44 -0
  40. package/src/executors/bounded-exec/host-memory.linux.ts +115 -0
  41. package/src/executors/bounded-exec/host-memory.ts +70 -0
  42. package/src/executors/bounded-exec/leaf-peak.ts +151 -0
  43. package/src/executors/bounded-exec/peak-waiter.ts +82 -0
  44. package/src/executors/bounded-exec/pool-admission.ts +64 -0
  45. package/src/executors/bounded-exec/run-cpu-pool.ts +20 -6
  46. package/src/executors/bounded-exec/verdict.ts +30 -1
  47. package/test-timings.json +134 -132
@@ -0,0 +1,115 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { posix } from 'node:path';
3
+ import type { HostMemory, RunMemory, RunMemoryError, RunMemoryReading } from './host-memory.js';
4
+
5
+ /**
6
+ * Linux's memory mechanisms. The run's memory is the least of the host's `MemTotal` and every finite `memory.max` of
7
+ * the cgroup v2 the run's process is in and of its ancestors, up to the root of the mounted hierarchy: the kernel holds
8
+ * a cgroup to its ancestors' limits too, so a job in cowshed's `background` class, whose own `memory.max` is `max`, has
9
+ * the class's three quarters of the host. A host with no cgroup v2 hierarchy, or a hierarchy that sets no limit, gives
10
+ * the run `MemTotal`.
11
+ */
12
+
13
+ const MEMINFO = '/proc/meminfo';
14
+ const CGROUP = '/proc/self/cgroup';
15
+ const MOUNTINFO = '/proc/self/mountinfo';
16
+
17
+ /** A file's text, or the errno code and message its read failed with. */
18
+ export type FileRead =
19
+ | { readonly ok: true; readonly text: string }
20
+ | { readonly ok: false; readonly code: string; readonly message: string };
21
+
22
+ const failed = (code: RunMemoryError['code'], subject: string, cause: string): RunMemoryReading => ({
23
+ ok: false,
24
+ error: { operation: 'read-run-memory', code, subject, cause },
25
+ });
26
+ const unreadable = (subject: string, read: Extract<FileRead, { ok: false }>): RunMemoryReading =>
27
+ failed('unreadable', subject, `${read.code}: ${read.message}`);
28
+
29
+ /** A mount point or root as mountinfo writes it, its space, tab, newline and backslash escaped in octal. */
30
+ const decodeOctal = (field: string): string =>
31
+ field.replace(/\\([0-7]{3})/g, (_, octal: string) => String.fromCharCode(Number.parseInt(octal, 8)));
32
+
33
+ /** The cgroup v2 mounts mountinfo lists: the cgroup each shows (`root`) and where (`point`). */
34
+ function cgroup2Mounts(mountinfo: string): { root: string; point: string }[] {
35
+ const mounts: { root: string; point: string }[] = [];
36
+ for (const line of mountinfo.split('\n')) {
37
+ const fields = line.split(' ');
38
+ const separator = fields.indexOf('-');
39
+ const [root, point] = [fields[3], fields[4]];
40
+ if (separator !== -1 && fields[separator + 1] === 'cgroup2' && root !== undefined && point !== undefined) {
41
+ mounts.push({ root: decodeOctal(root), point: decodeOctal(point) });
42
+ }
43
+ }
44
+ return mounts;
45
+ }
46
+
47
+ /** The run's memory, reading every file through `read`. */
48
+ export async function linuxRunMemory(read: (path: string) => Promise<FileRead>): Promise<RunMemoryReading> {
49
+ const meminfo = await read(MEMINFO);
50
+ if (!meminfo.ok) return unreadable(MEMINFO, meminfo);
51
+ const total = /^MemTotal:\s+(\d+) kB$/m.exec(meminfo.text)?.[1];
52
+ if (total === undefined) return failed('malformed', MEMINFO, 'it names no MemTotal in kB');
53
+ let least: RunMemory = { bytes: Number(total) * 1024, source: `${MEMINFO} MemTotal` };
54
+ const cgroups = await read(CGROUP);
55
+ if (!cgroups.ok) return unreadable(CGROUP, cgroups);
56
+ const path = /^0::(\/.*)$/m.exec(cgroups.text)?.[1];
57
+ if (path === undefined) {
58
+ // No cgroup v2 hierarchy holds the run: the host's memory is its memory.
59
+ return { ok: true, memory: least };
60
+ }
61
+ const mounts = await read(MOUNTINFO);
62
+ if (!mounts.ok) return unreadable(MOUNTINFO, mounts);
63
+ const mount = cgroup2Mounts(mounts.text).find(
64
+ ({ root }) => root === '/' || path === root || path.startsWith(`${root}/`),
65
+ );
66
+ if (mount === undefined) {
67
+ return failed('unmounted', path, `${MOUNTINFO} lists no cgroup2 mount that shows the run's cgroup`);
68
+ }
69
+ const top = posix.resolve(mount.point);
70
+ const own = posix.resolve(top, `.${mount.root === '/' ? path : path.slice(mount.root.length)}`);
71
+ if (own !== top && !own.startsWith(`${top}/`)) {
72
+ return failed('unmounted', path, `the run's cgroup lies outside the cgroup2 mount at ${top}`);
73
+ }
74
+ for (let directory = own; ; ) {
75
+ const file = posix.join(directory, 'memory.max');
76
+ const limit = await read(file);
77
+ if (limit.ok) {
78
+ const value = limit.text.trim();
79
+ if (value !== 'max') {
80
+ if (!/^\d+$/.test(value)) {
81
+ return failed('malformed', file, `it holds ${JSON.stringify(value)}, not max or bytes`);
82
+ }
83
+ // A limit above the host's memory (a near-2^63 one included) is no constraint, and is never made a number.
84
+ if (BigInt(value) < BigInt(least.bytes)) least = { bytes: Number(value), source: file };
85
+ }
86
+ } else if (limit.code !== 'ENOENT') {
87
+ // ENOENT: the hierarchy's root, or a cgroup whose parent enables no memory controller, has no limit of its own.
88
+ return unreadable(file, limit);
89
+ }
90
+ if (directory === top) break;
91
+ directory = posix.dirname(directory);
92
+ }
93
+ return { ok: true, memory: least };
94
+ }
95
+
96
+ async function readText(path: string): Promise<FileRead> {
97
+ try {
98
+ return { ok: true, text: await readFile(path, 'utf8') };
99
+ } catch (error) {
100
+ const code = error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : 'EIO';
101
+ return { ok: false, code, message: error instanceof Error ? error.message : String(error) };
102
+ }
103
+ }
104
+
105
+ /** Bun before 1.4.0 reports Linux's `ru_maxrss` as the kernel does, in KiB; from 1.4.0 it reports bytes. */
106
+ function peakBytes(maxRss: number, bunVersion: string): number {
107
+ const version = /^(\d+)\.(\d+)\./.exec(bunVersion);
108
+ if (version === null) {
109
+ throw new Error(`Bun names its version ${JSON.stringify(bunVersion)}, which is no semver`);
110
+ }
111
+ const [major, minor] = [Number(version[1]), Number(version[2])];
112
+ return major < 1 || (major === 1 && minor < 4) ? maxRss * 1024 : maxRss;
113
+ }
114
+
115
+ export const linuxMemory: HostMemory = { readRunMemory: () => linuxRunMemory(readText), peakBytes };
@@ -0,0 +1,70 @@
1
+ import { darwinMemory } from './host-memory.darwin.js';
2
+ import { linuxMemory } from './host-memory.linux.js';
3
+
4
+ /**
5
+ * The memory facts a run's CPU pool charges by (specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets
6
+ * itself"; 13_telemetry.md, "Job resource peaks"), read by each platform's own mechanism: `host-memory.linux.ts`,
7
+ * `host-memory.darwin.ts`. Callers read them here and never ask which platform they run on.
8
+ */
9
+ export interface HostMemory {
10
+ /** The memory the run's pool charges its leaves' peaks against. */
11
+ readRunMemory(): Promise<RunMemoryReading>;
12
+ /**
13
+ * A leaf's peak in bytes, from the `maxRSS` that Bun's `Subprocess.resourceUsage()` on `bunVersion` reports for
14
+ * it: the exited leaf's `ru_maxrss`.
15
+ */
16
+ peakBytes(maxRss: number, bunVersion: string): number;
17
+ }
18
+
19
+ /** The run's memory in bytes, and where it was read: the file or sysctl that holds it. */
20
+ export interface RunMemory {
21
+ readonly bytes: number;
22
+ readonly source: string;
23
+ }
24
+
25
+ /** Why the run's memory could not be read: the file or sysctl, and what reading it gave. */
26
+ export interface RunMemoryError {
27
+ readonly operation: 'read-run-memory';
28
+ /**
29
+ * `unreadable`: reading it failed; `malformed`: it held no byte count; `unmounted`: the run's cgroup v2 hierarchy is
30
+ * mounted nowhere this process can see; `unsupported-platform`: the platform has no reader.
31
+ */
32
+ readonly code: 'unreadable' | 'malformed' | 'unmounted' | 'unsupported-platform';
33
+ readonly subject: string;
34
+ readonly cause: string;
35
+ }
36
+
37
+ export type RunMemoryReading =
38
+ | { readonly ok: true; readonly memory: RunMemory }
39
+ | { readonly ok: false; readonly error: RunMemoryError };
40
+
41
+ /** A run whose memory cannot be read does not start: it is not shown to have room. */
42
+ export class RunMemoryUnreadable extends Error {
43
+ constructor(readonly error: RunMemoryError) {
44
+ super(
45
+ `bounded-exec: this run's memory cannot be read (${error.operation} ${error.code} ${error.subject}: ${error.cause}); a run whose memory cannot be read is not shown to have room, so it does not start`,
46
+ );
47
+ this.name = 'RunMemoryUnreadable';
48
+ }
49
+ }
50
+
51
+ const PLATFORMS: Partial<Record<NodeJS.Platform, HostMemory>> = { darwin: darwinMemory, linux: linuxMemory };
52
+
53
+ /** This platform's mechanisms, or null where it has none: there a leaf's peak goes unmeasured. */
54
+ export const HOST_MEMORY: HostMemory | null = PLATFORMS[process.platform] ?? null;
55
+
56
+ /** The run's memory on this platform, or why it cannot be read. */
57
+ export function readRunMemory(): Promise<RunMemoryReading> {
58
+ if (HOST_MEMORY === null) {
59
+ return Promise.resolve({
60
+ ok: false,
61
+ error: {
62
+ operation: 'read-run-memory',
63
+ code: 'unsupported-platform',
64
+ subject: process.platform,
65
+ cause: 'only Linux and macOS have a reader of the run memory',
66
+ },
67
+ });
68
+ }
69
+ return HOST_MEMORY.readRunMemory();
70
+ }
@@ -0,0 +1,151 @@
1
+ import type { IOType } from 'node:child_process';
2
+ import type { Readable } from 'node:stream';
3
+ import { fileURLToPath } from 'node:url';
4
+ import typia from 'typia';
5
+ import { HOST_MEMORY } from './host-memory.js';
6
+ import { resolveOnPath } from './runtime-pin.js';
7
+
8
+ /**
9
+ * A leaf's memory peak (specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets itself"; 13_telemetry.md, "Job
10
+ * resource peaks"): the exited command's rusage `ru_maxrss`, which its waiter (`peak-waiter.ts`) reads. The leaf runs
11
+ * no cgroup of its own, even under a cowshed supervisor, whose subtree of the command is an observed fold inside the
12
+ * job's cgroup (07_api.md, `JobSubtreeHandle`), so the peak is the rusage on Linux and macOS alike. The executor writes
13
+ * it into the task's record, and the task's next run is charged it in its run's pool.
14
+ */
15
+
16
+ /** The descriptor the waiter reports on: past the lifecycle channel (3), the subtree admission (4) and mbx's grant (5). */
17
+ export const PEAK_FD = 6;
18
+
19
+ /** The waiter's module, in the form this one was loaded in: compiled JavaScript under Nx, TypeScript under Bun. */
20
+ const WAITER = fileURLToPath(
21
+ new URL(import.meta.url.endsWith('.ts') ? './peak-waiter.ts' : './peak-waiter.js', import.meta.url),
22
+ );
23
+
24
+ /**
25
+ * One JSON line the waiter writes: the command's pid once it started it, then, once the command ended, its peak in
26
+ * bytes or why it has none.
27
+ */
28
+ type WaiterLine =
29
+ | { readonly started: number & typia.tags.Type<'uint32'> }
30
+ | { readonly peakBytes: number & typia.tags.Type<'uint64'> }
31
+ | { readonly unmeasured: string };
32
+ const isWaiterLine = typia.createEquals<WaiterLine>();
33
+
34
+ /** A leaf's peak in bytes, or why it went unmeasured. */
35
+ export type LeafPeak =
36
+ | { readonly kind: 'measured'; readonly bytes: number }
37
+ | { readonly kind: 'unmeasured'; readonly reason: string };
38
+
39
+ /** The Bun a leaf's waiter runs on, or why its peak goes unmeasured. */
40
+ export type PeakWaiter =
41
+ | { readonly kind: 'waiter'; readonly runtime: string }
42
+ | { readonly kind: 'unmeasured'; readonly reason: string };
43
+
44
+ /**
45
+ * The Bun that runs this executor, else the first `bun` on the executor's own PATH, never one a target's environment
46
+ * names: the waiter is the executor's, not the command's.
47
+ */
48
+ export function peakWaiter(): PeakWaiter {
49
+ if (HOST_MEMORY === null) {
50
+ return { kind: 'unmeasured', reason: `${process.platform} has no reader of a leaf's peak` };
51
+ }
52
+ const runtime =
53
+ process.versions.bun === undefined ? resolveOnPath('bun', process.env.PATH, process.cwd()) : process.execPath;
54
+ return runtime === null
55
+ ? { kind: 'unmeasured', reason: 'no bun is on PATH to wait on the command and read its rusage' }
56
+ : { kind: 'waiter', runtime };
57
+ }
58
+
59
+ /**
60
+ * The spawn of `file args` under the waiter on `runtime`. `descriptors` are the command's own past stderr, from fd 3:
61
+ * the waiter passes each one that is not ignored at its own number, and takes `PEAK_FD` for its report. The runtime's
62
+ * config is empty, so no preload a workspace's `bunfig.toml` names runs in the waiter.
63
+ */
64
+ export function underWaiter(
65
+ runtime: string,
66
+ file: string,
67
+ args: readonly string[],
68
+ descriptors: readonly IOType[],
69
+ ): { file: string; args: string[]; stdio: IOType[] } {
70
+ if (descriptors.length > PEAK_FD - 3) {
71
+ throw new RangeError(
72
+ `a leaf's own descriptors end before ${PEAK_FD}, the waiter's report; it names ${descriptors.length + 3}`,
73
+ );
74
+ }
75
+ const passed = descriptors.flatMap((io, at) => (io === 'ignore' ? [] : [at + 3]));
76
+ const padded = Array.from({ length: PEAK_FD - 3 }, (_, at): IOType => descriptors[at] ?? 'ignore');
77
+ return {
78
+ file: runtime,
79
+ args: ['--config=/dev/null', WAITER, String(PEAK_FD), passed.join(','), file, ...args],
80
+ stdio: ['pipe', 'pipe', 'pipe', ...padded, 'pipe'],
81
+ };
82
+ }
83
+
84
+ /** What a leaf's waiter reports on its descriptor. */
85
+ export interface WaiterReport {
86
+ /**
87
+ * The command's pid once the waiter started it: the leaf's runner, a member of the group the waiter leads. Null when
88
+ * the waiter ended without naming one.
89
+ */
90
+ readonly started: Promise<number | null>;
91
+ /** Once the waiter ends: the exited command's peak, or why it reported none. */
92
+ readonly peak: Promise<LeafPeak>;
93
+ }
94
+
95
+ /** What the waiter reports on `stream`: the command's pid as it starts it, and the command's peak once it ends. */
96
+ export function readWaiterReport(stream: Readable | null | undefined): WaiterReport {
97
+ if (stream === null || stream === undefined) {
98
+ return {
99
+ started: Promise.resolve(null),
100
+ peak: Promise.resolve({ kind: 'unmeasured', reason: 'the waiter was started without its report descriptor' }),
101
+ };
102
+ }
103
+ // `Promise.withResolvers` would read better but needs lib es2024; this package inherits lib es2022 from
104
+ // tsconfig.base.json. The report's close names null at the latest.
105
+ let name!: (pid: number | null) => void;
106
+ const started = new Promise<number | null>((named) => {
107
+ name = named;
108
+ });
109
+ // The waiter's last word: the line after its start, or what was wrong with a line.
110
+ let end: LeafPeak | null = null;
111
+ const line = (text: string): void => {
112
+ let parsed: unknown;
113
+ try {
114
+ parsed = JSON.parse(text);
115
+ } catch (error) {
116
+ if (!(error instanceof SyntaxError)) throw error;
117
+ }
118
+ if (!isWaiterLine(parsed)) {
119
+ end = { kind: 'unmeasured', reason: `the waiter reported ${JSON.stringify(text)}, which is no peak` };
120
+ } else if ('started' in parsed) {
121
+ name(parsed.started);
122
+ } else {
123
+ end =
124
+ 'peakBytes' in parsed
125
+ ? { kind: 'measured', bytes: parsed.peakBytes }
126
+ : { kind: 'unmeasured', reason: parsed.unmeasured };
127
+ }
128
+ };
129
+ let pending = '';
130
+ stream.setEncoding('utf8');
131
+ // eslint-disable-next-line deadline/no-unbounded-wait -- WHY unbounded: the report pipe is the waiter's alone (Bun closes every descriptor it does not pass), so it ends when the waiter does, and the executor's bounds end the waiter
132
+ const peak = new Promise<LeafPeak>((settle) => {
133
+ stream.on('data', (chunk: string) => {
134
+ pending += chunk;
135
+ for (let at = pending.indexOf('\n'); at !== -1; at = pending.indexOf('\n')) {
136
+ line(pending.slice(0, at));
137
+ pending = pending.slice(at + 1);
138
+ }
139
+ });
140
+ stream.once('error', (error: Error) => {
141
+ name(null);
142
+ settle({ kind: 'unmeasured', reason: `its report descriptor: ${error.message}` });
143
+ });
144
+ stream.once('close', () => {
145
+ if (pending.trim() !== '') line(pending.trim());
146
+ name(null);
147
+ settle(end ?? { kind: 'unmeasured', reason: 'the waiter ended before it could report the command' });
148
+ });
149
+ });
150
+ return { started, peak };
151
+ }
@@ -0,0 +1,82 @@
1
+ import { writeSync } from 'node:fs';
2
+ import { HOST_MEMORY } from './host-memory.js';
3
+
4
+ /**
5
+ * The waiter a leaf's command runs under (`leaf-peak.ts`; specs/cowshed/13_telemetry.md, "Job resource peaks"). Started
6
+ * on Bun as `bun --config=/dev/null peak-waiter.js <report fd> <fds> <file> [args…]`, it spawns `file args` with its
7
+ * own stdin, stdout and stderr and each descriptor `fds` names (comma-separated) at its own number, writes the
8
+ * command's pid to the report descriptor, waits for the command, writes its peak there, each as one JSON line, and
9
+ * ends as the command did: with its exit code, or with its signal raised on itself. Node, which runs the executor,
10
+ * reaps a child without its rusage; Bun's `Subprocess.resourceUsage()` reports it: `ru_maxrss`, the largest resident
11
+ * set any one process of the tree it waited on reached.
12
+ *
13
+ * The waiter leads the leaf's process group, so the executor's group signals reach the command directly: it ignores
14
+ * SIGINT, SIGTERM and SIGHUP and outlives the command to report it. A SIGKILL of the group ends it unreported. The
15
+ * command whose pid it names is the leaf's runner, which a hang snapshot samples (specs/cowshed/08_testing.md).
16
+ */
17
+
18
+ interface BunSubprocess {
19
+ readonly exited: Promise<number>;
20
+ readonly exitCode: number | null;
21
+ readonly signalCode: NodeJS.Signals | null;
22
+ readonly pid: number;
23
+ resourceUsage(): { readonly maxRSS: number } | undefined;
24
+ }
25
+
26
+ /** The two Bun APIs the waiter uses. */
27
+ interface BunSpawner {
28
+ readonly version: string;
29
+ spawn(argv: string[], options: { stdio: (number | 'inherit' | 'ignore')[] }): BunSubprocess;
30
+ }
31
+
32
+ function isBunSpawner(runtime: unknown): runtime is BunSpawner {
33
+ return (
34
+ typeof runtime === 'object' &&
35
+ runtime !== null &&
36
+ 'spawn' in runtime &&
37
+ typeof runtime.spawn === 'function' &&
38
+ 'version' in runtime &&
39
+ typeof runtime.version === 'string'
40
+ );
41
+ }
42
+
43
+ const IGNORED = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const;
44
+ const bun: unknown = Reflect.get(globalThis, 'Bun');
45
+ const [reportFd, list, file, ...args] = process.argv.slice(2);
46
+ if (!isBunSpawner(bun) || HOST_MEMORY === null || reportFd === undefined || list === undefined || file === undefined) {
47
+ throw new Error('peak-waiter runs on Bun, on Linux or macOS, as `peak-waiter.js <report fd> <fds> <file> [args…]`');
48
+ }
49
+ const report = (line: { started: number } | { peakBytes: number } | { unmeasured: string }): void => {
50
+ try {
51
+ writeSync(Number(reportFd), `${JSON.stringify(line)}\n`);
52
+ } catch {
53
+ // The executor that would read the report is gone.
54
+ }
55
+ };
56
+ const passed = list === '' ? [] : list.split(',').map(Number);
57
+ const stdio: (number | 'inherit' | 'ignore')[] = ['inherit', 'inherit', 'inherit'];
58
+ for (let fd = 3; fd <= Math.max(2, ...passed); fd += 1) stdio.push(passed.includes(fd) ? fd : 'ignore');
59
+ const ignore = (): void => {};
60
+ for (const signal of IGNORED) process.on(signal, ignore);
61
+ let child: BunSubprocess;
62
+ try {
63
+ child = bun.spawn([file, ...args], { stdio });
64
+ } catch (error) {
65
+ const reason = error instanceof Error ? error.message : String(error);
66
+ report({ unmeasured: `the command did not start: ${reason}` });
67
+ writeSync(2, `bounded-exec: could not start ${file}: ${reason}\n`);
68
+ process.exit(1);
69
+ }
70
+ report({ started: child.pid });
71
+ await child.exited;
72
+ const usage = child.resourceUsage();
73
+ report(
74
+ usage === undefined
75
+ ? { unmeasured: 'Bun read no resource usage for the exited command' }
76
+ : { peakBytes: HOST_MEMORY.peakBytes(usage.maxRSS, bun.version) },
77
+ );
78
+ if (child.signalCode !== null) {
79
+ for (const signal of IGNORED) process.removeListener(signal, ignore);
80
+ process.kill(process.pid, child.signalCode);
81
+ }
82
+ process.exit(child.exitCode ?? 1);
@@ -0,0 +1,64 @@
1
+ /**
2
+ * The admission decision of a CPU pool (`cpu-pool.ts`; specs/cowshed/05_gateway.md, "Without mbx, every Nx run budgets
3
+ * itself"): which queued requests a pool grants, in FIFO order, from the tokens it has free and, for a run's own pool,
4
+ * the run's memory. Pure: the pool reads its jobserver fifo for the free count and keeps the holders' charges, and this
5
+ * decides.
6
+ *
7
+ * Every grant needs both. The head takes `min(want, free)` tokens once one is free, and only while the charges of the
8
+ * leaves holding grants plus its own fit the run's memory; a head that cannot be granted holds up every request behind
9
+ * it, and no request holds part of a grant while it waits for the rest. A leaf is charged its task's last recorded
10
+ * memory peak, and nothing while its task has none. A leaf whose own charge alone exceeds the run's memory could never
11
+ * fit, so it is granted once nothing else holds memory, and the grant says so.
12
+ */
13
+
14
+ /** What a queued request asks: whole tokens, at least one, and its charge in bytes (0 for a task with no peak). */
15
+ export interface PoolAsk {
16
+ readonly want: number;
17
+ readonly memory: number;
18
+ }
19
+
20
+ /** The run's memory a pool charges against, and the bytes its holders are charged; null for a pool that charges none. */
21
+ export interface MemoryLedger {
22
+ readonly capacity: number;
23
+ readonly held: number;
24
+ }
25
+
26
+ /** One request's grant: the request, its tokens, and whether its charge alone exceeds the run's memory. */
27
+ export interface PoolGrant<Ask extends PoolAsk> {
28
+ readonly request: Ask;
29
+ readonly tokens: number;
30
+ readonly oversized: boolean;
31
+ }
32
+
33
+ /**
34
+ * The grants of the queue's first requests, in its order, and what the first request left waiting waits for: free
35
+ * tokens (`cpu`) or the run's memory (`memory`). `waiting` is null when every request was granted.
36
+ */
37
+ export interface Admission<Ask extends PoolAsk> {
38
+ readonly grants: readonly PoolGrant<Ask>[];
39
+ readonly waiting: 'cpu' | 'memory' | null;
40
+ }
41
+
42
+ export function admit<Ask extends PoolAsk>(
43
+ queue: readonly Ask[],
44
+ available: number,
45
+ memory: MemoryLedger | null,
46
+ ): Admission<Ask> {
47
+ const grants: PoolGrant<Ask>[] = [];
48
+ let free = available;
49
+ let held = memory?.held ?? 0;
50
+ for (const request of queue) {
51
+ const oversized = memory !== null && request.memory > memory.capacity;
52
+ if (memory !== null && held + request.memory > memory.capacity && !(oversized && held === 0)) {
53
+ return { grants, waiting: 'memory' };
54
+ }
55
+ const tokens = Math.min(request.want, free);
56
+ if (tokens === 0) {
57
+ return { grants, waiting: 'cpu' };
58
+ }
59
+ free -= tokens;
60
+ held += request.memory;
61
+ grants.push({ request, tokens, oversized });
62
+ }
63
+ return { grants, waiting: null };
64
+ }
@@ -5,6 +5,7 @@ import { logger } from 'nx/src/devkit-exports.js';
5
5
  import type { PostTasksExecutionContext, PreTasksExecutionContext } from 'nx/src/project-graph/plugins/public-api.js';
6
6
  import { type CloseOutcome, type CpuPool, readInheritedCpuPool } from './cpu-pool.js';
7
7
  import type { CpuPoolThreadData, CpuPoolThreadReport } from './cpu-pool-thread.js';
8
+ import { type RunMemoryReading, RunMemoryUnreadable, readRunMemory } from './host-memory.js';
8
9
  import { mbxPool } from './mbx-pool.js';
9
10
  import { CPU_TOKENS_ENV, parseInheritedTokens } from './runner-sizing.js';
10
11
 
@@ -23,6 +24,10 @@ import { CPU_TOKENS_ENV, parseInheritedTokens } from './runner-sizing.js';
23
24
  * one token per core, or the inherited positive `BOUNDED_EXEC_CPU_TOKENS` when that is fewer: inside a cowshed job
24
25
  * that count is the job's own, so the job's `--want` bounds the run.
25
26
  *
27
+ * The pool also charges memory: each leaf is charged its task's last recorded peak, and granted only while the charges
28
+ * of the leaves holding grants and its own fit the run's memory (`host-memory.ts`: the cgroup's `memory.max` on Linux,
29
+ * else the host's). A run whose memory cannot be read does not start.
30
+ *
26
31
  * The pool runs on a thread of its own (`cpu-pool-thread.ts`). The process that serves it, the Nx daemon when installed
27
32
  * plugins load in it or the Nx CLI without one, hashes the run's tasks and builds its project graph in synchronous calls
28
33
  * on its main thread. In a gate on 2026-10-28 one `hashPlans` ran for 14.2 s, and sixteen runners queued on a pool on
@@ -67,20 +72,26 @@ export function runPoolTokens(env: Readonly<NodeJS.ProcessEnv>, cores: number):
67
72
  }
68
73
 
69
74
  /**
70
- * Serve `context`'s run a pool of `runPoolTokens` and publish it in `env`, which every task inherits, unless the run
71
- * is served none. A pool that cannot be made is said, and the run's tasks are then sized only by the ceilings they
72
- * inherit.
75
+ * Serve `context`'s run a pool of `runPoolTokens`, charged against the run's memory `readMemory` reads, and publish it
76
+ * in `env`, which every task inherits, unless the run is served none. A run whose memory cannot be read throws
77
+ * `RunMemoryUnreadable`, which fails the run before any task starts: it is not shown to have room. A pool that cannot
78
+ * be made is said, and the run's tasks are then sized only by the ceilings they inherit.
73
79
  */
74
80
  export async function serveRunCpuPool(
75
81
  context: Pick<PreTasksExecutionContext, 'id'>,
76
82
  env: NodeJS.ProcessEnv = process.env,
77
83
  cores: number = availableParallelism(),
84
+ readMemory: () => Promise<RunMemoryReading> = readRunMemory,
78
85
  ): Promise<void> {
79
86
  const tokens = runPoolTokens(env, cores);
80
87
  if (tokens === null) {
81
88
  return;
82
89
  }
83
- const served = await servePoolThread(tokens);
90
+ const memory = await readMemory();
91
+ if (!memory.ok) {
92
+ throw new RunMemoryUnreadable(memory.error);
93
+ }
94
+ const served = await servePoolThread(tokens, memory.memory.bytes);
84
95
  if (!served.ok) {
85
96
  logger.warn(
86
97
  `bounded-exec: this run's CPU pool failed (${served.error}); its tasks are sized only by the ceilings they inherit`,
@@ -99,8 +110,11 @@ export async function serveRunCpuPool(
99
110
  * has said how its pool closed fails whichever wait is open, a later close returns that failure, and a thread lost while
100
111
  * its pool serves is said at once.
101
112
  */
102
- function servePoolThread(tokens: number): Promise<ServedPool> {
103
- const thread = new Worker(THREAD_ENTRY, { workerData: { tokens } satisfies CpuPoolThreadData, ...THREAD_PRELOAD });
113
+ function servePoolThread(tokens: number, memory: number): Promise<ServedPool> {
114
+ const thread = new Worker(THREAD_ENTRY, {
115
+ workerData: { tokens, memory } satisfies CpuPoolThreadData,
116
+ ...THREAD_PRELOAD,
117
+ });
104
118
  return new Promise<ServedPool>((served) => {
105
119
  let state: ThreadState = { kind: 'starting', served };
106
120
  let closing: Promise<CloseOutcome> | undefined;
@@ -101,6 +101,13 @@ export interface BoundedExecRecord {
101
101
  * expired; written for the reader of a refused run, never read back.
102
102
  */
103
103
  readonly cpuWait?: CpuWaitRow;
104
+ /**
105
+ * The command's memory peak in bytes when it ended (specs/cowshed/13_telemetry.md, "Job resource peaks"): its rusage
106
+ * `ru_maxrss`, the largest resident set any one process of its tree reached, as its waiter read it (`leaf-peak.ts`).
107
+ * Null when it was not measured: the command never ran, the waiter ended before it, or no Bun waited on it; never
108
+ * zero for that. The task's next run is charged it in its run's pool (`readLastPeak`).
109
+ */
110
+ readonly peakBytes: number | null;
104
111
  }
105
112
 
106
113
  /** The Nx task a run executes as. Nx gives an executor no task id, only its parts. */
@@ -488,6 +495,23 @@ export async function readRecord(directory: string): Promise<BoundedExecRecord |
488
495
  return parseRecord(JSON.parse(text));
489
496
  }
490
497
 
498
+ /**
499
+ * The peak the task's last record in `directory` names: its charge in its run's pool. Null when the task has no record
500
+ * or its record no peak; a record that cannot be read is an error naming it, never a charge of nothing.
501
+ */
502
+ export async function readLastPeak(
503
+ directory: string,
504
+ ): Promise<{ ok: true; peakBytes: number | null } | { ok: false; error: string }> {
505
+ try {
506
+ return { ok: true, peakBytes: (await readRecord(directory))?.peakBytes ?? null };
507
+ } catch (error) {
508
+ return {
509
+ ok: false,
510
+ error: `the task's last record ${join(directory, VERDICT_FILE)} cannot be read: ${error instanceof Error ? error.message : String(error)}`,
511
+ };
512
+ }
513
+ }
514
+
491
515
  /** The JUnit report a command wrote into `directory`, or `null` when it wrote none. */
492
516
  export async function readJunitReport(
493
517
  directory: string,
@@ -511,7 +535,12 @@ function parseRecord(value: unknown): BoundedExecRecord {
511
535
  if (!isObject(value) || typeof value.task !== 'string' || !(typeof value.hash === 'string' || value.hash === null)) {
512
536
  throw new Error(`not a bounded-exec record: ${JSON.stringify(value)}`);
513
537
  }
514
- return { task: value.task, hash: value.hash, verdict: parseVerdict(value.verdict) };
538
+ // A record written before peaks were recorded carries none.
539
+ const peakBytes = value.peakBytes ?? null;
540
+ if (!(peakBytes === null || (typeof peakBytes === 'number' && Number.isSafeInteger(peakBytes) && peakBytes >= 0))) {
541
+ throw new Error(`not a bounded-exec record: ${JSON.stringify(value)}`);
542
+ }
543
+ return { task: value.task, hash: value.hash, verdict: parseVerdict(value.verdict), peakBytes };
515
544
  }
516
545
 
517
546
  function parseVerdict(value: unknown): BoundedExecVerdict {