Startup snapshots for compiled executables (bun build --snapshot)

[Jarred-Sumner]

Combined branch, kept open only for its CI matrix. The reviewable form is the stack: #37259 (deps) → #37260 (runtime + Bun.startupSnapshot) → #37261 (bun build --snapshot) → #37262 (tooling); this PR closes once that is in. Depends on oven-sh/mimalloc#13 and oven-sh/WebKit#397; the branch pins to preview artifacts, so it builds as-is.

What it does

bun build --compile --snapshot builds the executable, runs it once, and when startup has drained the runtime writes a snapshot of the started-up process (evaluated modules, everything startup built, JIT code) and embeds it, as is, in the executable. Later launches map the executable's own pages and continue in the event loop instead of booting; process.on('restore') runs first. Docs: docs/bundler/startup-snapshots.mdx.

Surface
bun build --compile --snapshot[=auto|manual] --snapshot-io=strict|local|network	auto: taken once startup drains; manual: the app calls take(). Default io policy refuses fs/spawn/dns/net while the snapshot is taken; local/network allow and report every use with call sites. The build also reports env reads, process.env copies and std streams set up before the snapshot. No snapshot → the build fails and says why.
bun build --snapshot --outfile exe	The snapshot step alone, on an executable built earlier, in place and re-runnable (cross-compile anywhere, snapshot on the target). The build tells the executable to take its snapshot through a marking in its own payload; nothing goes through env or argv.
Bun.build({ compile, snapshot: true | { mode, io } })	Same thing programmatically; throws without compile.
Bun.startupSnapshot.main(fn)	For tools: imports go into the snapshot, fn runs after restore with the launch's own argv/cwd/env/stdio; such a snapshot is valid for any argv and keeps compiled code.
Bun.startupSnapshot.take({ timers, envGate }), isBuildingSnapshot(), epoch(), reclean(), process.on('restore')	Manual mode and introspection.

Area	Files
Take + restore	src/jsc/bindings/StartupSnapshot.{h,cpp}: region dump (adjacent runs merged, JIT pages re-counted after the write), __DATA overlay (Linux: minus the payload), extern-library fixups, argv key, env gate, page-size/build identity, dlopen replay, verbose timing marks
What a resumed process re-derives	run_command.rs restore sequence + hooks in io, http, threading, jsc/{event_loop,rare_data,VirtualMachine}, runtime/{timer,dns_jsc,node/*,socket}, bun_core/{startup_snapshot,util,env_var,output}: clocks, PRNG, timers (rebased), DNS cache, dead-fd hangups, env caches, thread pools, fs watchers, stdio (tty flags, termios, colors, Bun.std*, process.std* — terminal streams kept in place and resized, others rebuilt), signal handlers behind process.on(signal)
Env hygiene	JSEnvironmentVariableMap, SharedEnvStore.h, BunProcess.cpp: store-backed process.env during the build so it can be refilled in place at restore; build-time report of reads and copies
API	src/runtime/api/StartupSnapshotObject.rs, bun.d.ts
Build	Arguments.rs, build_command.rs, JSBundler.rs, js_bundle_completion_task.rs, StandaloneModuleGraph.rs (payload marking, embed/re-embed), exe_format/elf.rs (re-injection into an executable that already carries a payload)
Support predicate	Compiled in on macOS (with the mimalloc zone override, BUN_MIMALLOC_ZONE_OVERRIDE) and glibc Linux; off under ASAN; stubs elsewhere. bun build --snapshot reports unavailability up front; the tests probe it.
Tooling	StartupSnapshotTooling.cpp, compiled only with -DBUN_STARTUP_SNAPSHOT_TOOLING=1
Tests	test/js/bun/startup-snapshot/: 21 tests — round trips, embedded restore, GC after restore, timers, spawnSync, RNG/time, DNS, polls, fs.watch, env gate, auto mode, split step, Bun.build, io policy, main(), stdio (three cases), signals, wasm, wasm tier-up race

Numbers

Cost when unused, on matched baselines: JetStream2 at parity (+0.05% on medians, 5 interleaved pairs); allocation-churn peak RSS equal or lower; hello-world +0.1 MB; full JSTests/stress differential against a stock shell identical (5,599 tests). Plain compiled executables with bytecode get ~20 MB smaller because instruction streams alias the embedded cache.

A large interactive application (one real turn, then idle): 228–232 MB / ~1.4–2.1 s CPU plain → 144–158 MB / 0.7–1.1 s from the snapshot; +174 MB binary.

Command-line tools, each built with --bytecode versus the same build plus a snapshot (Linux: Debian 12 arm64 container, CI binary; private memory is RssAnon at exit):

tool	wall clock	private memory	snapshot
babel + preset-env	50.9 → 26.8 ms	38.5 → 20.2 MB	50 MB
postcss + autoprefixer	45.5 → 17.3 ms	32.6 → 17.4 MB	35 MB
sass	36.0 → 14.0 ms	33.1 → 17.2 MB	36 MB
typescript	29.4 → 12.0 ms	32.0 → 16.2 MB	31 MB
prettier (5 plugins)	21.9 → 13.8 ms	20.6 → 11.2 MB	25 MB
markdown-it	9.6 → 7.9 ms	7.7 → 6.6 MB	8 MB
yaml	8.6 → 8.2 ms	7.2 → 7.3 MB	7 MB
esbuild-wasm, module warmed	117 → 24 ms (plain)		135 MB
noop (floor)	2.1 → 2.1 ms (plain)		6 MB

macOS numbers for the same tools are smaller wins on wall clock (a snapshot launch there is one extra exec, whose price is machine-dependent: typescript −20%, babel −37%, autoprefixer −43%, prettier/markdown-it/yaml flat to +20%) with the same 60–65% drop in user CPU; typescript's footprint goes 37 → 24 MB.

Not in this PR

The macOS build option (mimalloc as the process malloc zone) that snapshots need is not enabled in official builds; that is a separate decision. musl support is gated off until its dump crash is debugged. Table evacuation at restore is still unconditional (a memory-first choice that a main()-style build could skip).