perf(core): limit each worker's heap to 512MB

V8 lets a heap grow to several times its live data before collecting
it, the more the higher its limit: four times from 2GB up, and on a
machine with plenty of memory every worker's limit is 4GB, so each held
several times what it was using.

Each worker's old space is now limited to `WORKER_HEAP_SIZE` (512MB).
The biggest page of the Node.js docs, `all.html`, takes ~300MB. Node's
`--max-old-space-size` replaces the limit, to raise it, and it's what
limits the main thread, which runs the generators with one thread.

On Node core's build with 4 threads, the peak goes from 2.02GB to
1.67GB on Node 26, and from 2.44GB to 2.19GB on Node 24, for 3-5% more
time spent collecting garbage. The build passes with workers limited to
as little as ~350MB.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

docs/configuration.md

@@ -134,7 +134,8 @@ these for that generator alone, except `markdown`, which it adds to.
 Top-level, alongside `target` and `global`:
 
 - `threads` {number} Worker threads used for generation. Defaults to your
-  CPU count.
+  CPU count. Each worker's heap is limited to 512MB; raise it with Node.js's
+  `--max-old-space-size` (`NODE_OPTIONS` takes it too).
 - `chunkSize` {number} Items processed per worker thread. **Default:** `10`.
 
 ## Generator options

packages/core/src/threading/constants.mjs

@@ -0,0 +1,10 @@
+'use strict';
+
+/**
+ * The heap size limit of each worker thread (V8's old space), in MB. V8 lets a
+ * heap grow to several times its live data before collecting it, the more the
+ * higher its limit, so every worker held several times what it was using. The
+ * biggest page of the Node.js docs, `all.html`, takes ~300MB. Node.js's
+ * `--max-old-space-size` replaces it.
+ */
+export const WORKER_HEAP_SIZE = 512;

packages/core/src/threading/index.mjs

@@ -2,6 +2,8 @@ import Piscina from 'piscina';
 
 import logger from '#logger/index.mjs';
 
+import { WORKER_HEAP_SIZE } from './constants.mjs';
+
 const poolLogger = logger.child('WorkerPool');
 
 const workerScript = import.meta.resolve('./chunk-worker.mjs');
@@ -23,6 +25,7 @@ export default function createWorkerPool(threads) {
     minThreads: 0,
     maxThreads: threads,
     idleTimeout: 1_000,
+    resourceLimits: { maxOldGenerationSizeMb: WORKER_HEAP_SIZE },
     workerData: { logLevel: logger.getLogLevel() },
   });
 }