perf(engine): bump worker count cap for high-core hosts (hf#732 PR 1/5)

[vanceingalls]

Summary

PR 1 of 5 in the hf#732 decomposition stack. Bumps parallelCoordinator's worker-count caps so high-core hosts can actually surface their hardware to renders:

• ABSOLUTE_MAX_WORKERS: 10 → 24 (explicit --workers 16 now surfaces 16 DOM sessions instead of being silently clamped).
• DEFAULT_SAFE_MAX_WORKERS constant → defaultSafeMaxWorkers() function returning max(6, min(16, floor(cpus/8))). On <=32-core hosts: unchanged (still 6). On 64/96/128-core hosts: 8/12/16.

No behavior change for typical hosts. Required prerequisite for the hybrid shader-transition path landed in PR 4.

Test plan

• Existing 7 parallelCoordinator tests pass
• Engine typecheck clean
• oxlint clean

Stack

This is the base of the hf#732 decomposition stack:

1. PR 1 (this) — perf(engine): worker-count cap bump
2. PR 2 — feat(producer): add pngDecodeBlitWorkerPool
3. PR 3 — feat(producer): add shaderTransitionWorkerPool
4. PR 4 — perf(producer): hybrid layered/parallel path (the 2.22× speedup)
5. PR 5 — perf(producer): pipeline capture and shader-blend per-frame

Replaces the closed hf#732. See that issue for the original investigation; the architectural mismatch with #733's captureHdrStage extraction made a clean rebase impossible.

— Vai

---

Relates to #677

[vanceingalls]

• perf(engine): use HeadlessExperimental.beginFrame for alpha PNG capture #787
• chore(lefthook): grandfather 3 pre-existing over-cap engine files #788
• perf(producer): pipeline capture and shader-blend per-frame (hf#732 PR 5/5) #760
• perf(producer): hybrid layered/parallel path for SDR shader-transition renders (hf#732 PR 4/5) #759
• feat(producer): add shaderTransitionWorkerPool (hf#732 PR 3/5) #758
• feat(producer): add pngDecodeBlitWorkerPool (hf#732 PR 2/5) #757
• perf(engine): bump worker count cap for high-core hosts (hf#732 PR 1/5) #756 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Verdict: APPROVE — clean worker-cap bump

Per Rule 5: required CI all green at 327a47b1 — Lint, Build, Test, Typecheck, regression, all regression-shards (including hdr), preview-regression, Smoke: global install, player-perf, CodeQL. Windows tests + render failed but those are pre-existing red on main (confirmed across the stack); not introduced by this PR.

Originally skipped this one per Vance's ❌ signal in Slack — re-reviewing now at Miguel's request.

Math checks out

defaultSafeMaxWorkers() = Math.max(6, Math.min(16, Math.floor(cpus().length / 8)))

Worked through the table from the PR description:

cpus()	floor/8	min(16, …)	max(6, …)
4	0	0	6
8	1	1	6
32	4	4	6
48	6	6	6
64	8	8	8
96	12	12	12
128	16	16	16
192	24	16	16

Boundary at 48 cores (still 6) is the right place to keep typical dev/CI hosts unchanged. The 64+ tier scales linearly until the 16-worker ceiling. PR description's "<=32-core hosts: unchanged (still 6). On 64/96/128-core hosts: 8/12/16" matches.

The /8 divisor rationale is in the docstring: "leaves headroom for each Chrome worker's SwiftShader compositor + the shader-blend thread pool" — empirically validated by the 2.22× speedup PRs (#759/#760) downstream.

ABSOLUTE_MAX_WORKERS = 24

Explicit --workers N now surfaces up to 24 (was clamped at 10). Above 24 the cap intentionally clamps — docstring at :65-69 documents the reason ("CDP-protocol dispatch through Node's main event loop and OS scheduling noise overwhelms any further parallelism"). Reasonable upper bound.

Observations (non-blocking)

1. No new test for the function — the change from const DEFAULT_SAFE_MAX_WORKERS = 6 to defaultSafeMaxWorkers() switches from a value to a function but doesn't add a test pinning the formula at boundary cores (8, 48, 64, 96, 128, 192). Existing 7 parallelCoordinator tests pass per the PR description — they pin the call-site behavior but not the underlying formula. Worth a small follow-up like:

   it("clamps default workers to [6, 16] based on cpu count", () => {
     // mock cpus()
     expect(defaultSafeMaxWorkers()).toBe(6); // 32 cores
     expect(defaultSafeMaxWorkers()).toBe(8); // 64 cores
     expect(defaultSafeMaxWorkers()).toBe(16); // 128 cores
     expect(defaultSafeMaxWorkers()).toBe(16); // 192 cores (capped)
   });

   Not gating — boundary math is simple enough to read off, and the downstream stack tests it integratively.

2. cpus() syscall on each calculateOptimalWorkers call — cpus() returns an array of CPU info objects; on Linux it reads /proc/cpuinfo. Minor cost in absolute terms but it's called per render-start, not per frame. Caching the count at module-load would be tidier:

   const CPU_COUNT = cpus().length;
   function defaultSafeMaxWorkers(): number { return Math.max(6, Math.min(16, Math.floor(CPU_COUNT / 8))); }

   But this loses the (admittedly hypothetical) ability to respond to hot-plug CPU changes during a long-running process. Negligible either way.

Praise

• The function-form rationale (high-core hosts surfacing their hardware to auto concurrency) is exactly the right framing — operators shouldn't need to know the magic --workers N value for their hardware.
• Inline comments explain WHY (CDP dispatch ceiling, SwiftShader headroom) not just WHAT. Future-me will understand the constants without git-blame archaeology.
• Foundation PR is correctly small and self-contained — the rest of the stack builds on this without polluting the diff.

Review by Rames Jusso (pr-review)

[miguel-heygen]

Clean, well-scoped change. Reviewed the logic and CI state:

Correctness: The defaultSafeMaxWorkers() math holds — max(6, min(16, floor(cpus/8))) returns 6 for ≤48 cores (no behavior change for typical hosts), scales linearly to 16 at 128 cores, and caps there. The /8 divisor leaves ample headroom for SwiftShader + shader-blend threads per worker. ABSOLUTE_MAX_WORKERS bump to 24 only applies to explicit --workers N requests, so auto-mode users are unaffected.

Runtime safety: cpus().length is evaluated per-call (not module-load), so hot-path or container cgroup changes are handled correctly. The os.cpus import was already present — no new dependency.

Tests: The existing 7 parallelCoordinator tests pass. The two calculateOptimalWorkers tests exercise both auto-mode and explicit-request paths. A minor nice-to-have would be a test that asserts calculateOptimalWorkers(1000, undefined, { concurrency: "auto" }) returns the expected value for the CI host's core count (or a mocked os.cpus), but that's not blocking — the function is pure math and the formula is trivially verifiable.

CI failures (file size check, windows render/tests) are all pre-existing and unrelated to this change. Required checks (build, lint, typecheck, test, CLI smoke, regressions) all pass.

LGTM. Good base for the hf#732 stack.

— Magi