M5: Bootstrap driver — run compiled bin/compile.php instead of Zend php

[PurHur]

Milestone

M5 — compiled bootstrap driver replaces Zend loop (parent #1492)

Problem

Every bootstrap gate still invokes php bin/compile.php for link/emit. M3 strict and M4 loop slice are green on harness 2026-05-27 (emit_path=native), but the production driver is not yet emitted by gen-1:

Target	Native emit via ./script/bootstrap-selfhost-helloworld-compile-bin.sh	Notes
examples/000-HelloWorld/example.php	✅	M3 strict
lib/Compiler.php	✅	M3 sidecar fast path
bin/compile.php	❌	#2697 — link-time sidecar segfault
bin/vm.php, src/cli_driver.php	❌	#2699

Scope

Path	Work
bin/compile.php	Gen-0 output target; gen-1 must compile next revision
test/selfhost/compiler_helloworld_smoke/compile_driver.php	Native compile dispatch (PHP_COMPILER_M3_RUNTIME_COMPILE=1)
script/bootstrap-selfhost-helloworld-compile-bin.sh	M5 repro script (exists; extend for driver matrix)
script/bootstrap-selfhost-link.sh	Gen-0 Zend link (stays until cold boot #1416)
Bootstrap scripts	Replace php bin/compile.php invocations with build/selfhost-compile-driver when green
lib/JIT.php, lib/Cli/	Driver hot path lowering (#2697)

Repro (today)

# Green M4 slice (not driver):
./script/docker-exec.sh -- bash -lc 'make bootstrap-loop-probe'

# M5 blocker — driver emit:
./script/docker-exec.sh -- bash -lc '
  export PHP_COMPILER_M3_SOURCE=/compiler/bin/compile.php
  export PHP_COMPILER_M3_OUT=/compiler/build/compile-php-aot
  ./script/bootstrap-selfhost-helloworld-compile-bin.sh
'
# helloworld_compile_smoke: parseAndCompile returned null — see #2697

Done when

• Documented two-stage bootstrap: (1) Zend gen-0 link, (2) gen-0+ native-emits bin/compile.php → gen-1 driver
• make bootstrap-selfhost-driver-smoke (or equivalent) uses compiled driver for a tiny fixture — no php bin/compile.php on emit step
• docs/bootstrap-selfhost.md row “Bootstrap driver” = compiled path ✅
• Opt-in BOOTSTRAP_M5_DRIVER_GATE=1 in ci-local.sh llvm tail; default-on follow-up after stable
• Unblocks retiring Zend from routine bootstrap (M5: Prelink vendor (php-cfg, php-types, php-llvm) — no composer at cold boot #1416 cold boot is separate)

Unblock order

#2697 bin/compile.php sidecar/AOT segfault
  → #2699 bin/vm.php + src/cli_driver.php
  → this issue (#1521) swap bootstrap scripts to compiled driver
  → #1416 vendor prelink (no composer at cold boot)

Links

#1492 · #2600 · #2697 · #2699 · #1416 · #1520 (stub retirement)

[PurHur]

Implementation hints (batch 101)

Two-stage bootstrap (document in docs/bootstrap-m5-fast-path.md)

Stage	Driver	Output
Gen-0 (last Zend)	php bin/compile.php + make bootstrap-selfhost-link	Native build/selfhost-* with stubs
Gen-1+	./build/selfhost-compile-driver (name TBD)	AOT emit without php bin/compile.php

Files to touch first

Piece	Path	Notes
Compile driver entry	bin/compile.php, test/selfhost/compile_driver_smoke/	Same graph as #1937 strict emit
CLI wrapper	bin/phpc.php / lib/Cli/	Route phpc build to native driver when env set
Env switch	PHP_COMPILER_NATIVE_DRIVER=1	Opt-in before default-on
CI gate	NATIVE_COMPILE_DRIVER_GATE=0 in script/ci-defaults.env	Flip after #1937 + #1968 green
Makefile	bootstrap-native-driver-smoke	Wrap probe script

Unblock order

1. Self-host M3: Native emit for compiler compile-smoke fixture (post-#1493) #1937 / Self-host M3: Wire compile_driver_smoke.php into native AOT emit (no Zend compile.php) #1977 ✅ — compile-smoke runtime native path
2. Self-host M3: Native emit for compiler compile-smoke fixture (post-#1493) #1937 strict — emit path uses native Runtime::parseAndCompile (no Zend fallback)
3. M2/M5: Retire PHP_COMPILER_SELFHOST_AOT stubs on Compiler compile spine #1520 — shrink stub surface so driver behavior is real
4. This issue — swap php bin/compile.php → native binary in bootstrap-wave-check.sh tail
5. M5: Prelink vendor (php-cfg, php-types, php-llvm) — no composer at cold boot #1416 — vendor prelink (orthogonal cold boot)

Verify (local / Docker only)

BOOTSTRAP_M3_COMPILE_SMOKE_STRICT=1 ./script/bootstrap-selfhost-compile-smoke-probe.sh
# then (when implemented):
NATIVE_COMPILE_DRIVER_GATE=1 ./script/bootstrap-wave-check.sh
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev make bootstrap-wave-check

Epic: #1492. Do not require GitHub Actions (#394 ✅).

[PurHur]

Implementation-ready update (harness 2026-05-27)

Emit path is green — blockers #2697 / #2699 closed; repros pass on master:

Target	Command	Result
bin/compile.php	PHP_COMPILER_M3_SOURCE=bin/compile.php ./script/bootstrap-selfhost-helloworld-compile-bin.sh	✅ compile OK
bin/vm.php	make bootstrap-selfhost-cli-driver-emit	✅ native
src/cli_driver.php	same	✅ native
M4 slice	make bootstrap-loop-probe	✅ exit 0

Remaining work (this issue): integration only — add make bootstrap-selfhost-driver-smoke (#2769) and replace php bin/compile.php in script/bootstrap-selfhost-link.sh / bootstrap-wave-check.sh with gen-1 artifact.

Unblock order (revised):

#2768 php-llvm vendor prelink (Expr_Closure)
  → #2769 driver-smoke gate
  → #1521 script swap (this issue)
  → #2770 cold boot without vendor/

[PurHur]

Correction: cold-boot without vendor/ is #2771 (not #2770). #2770 is M4 full-spine CI gate.

[PurHur]

Landed partial M5 driver plumbing in #2774:

• Explicit `php_compiler_cli_dispatch()` entry from `bin/compile.php` / `bin/vm.php` (AOT require does not re-run cli init)
• `PHP_COMPILER_M5_DRIVER_HOST` sidecar-stub bypass hook in `lib/JIT.php`
• `make bootstrap-selfhost-driver-smoke` documents honest partial status (sidecar link OK; execute blocked)

Next blocker (repro): `BOOTSTRAP_M5_DRIVER_HOST_FULL_CLI=1 ./script/bootstrap-selfhost-driver-host-compile.sh` → LLVM 9 link segfault (exit 139) when bundling full `src/cli_driver.php`. Needs native `$argv` init in standalone AOT + `M5CompileDriverMainNative` argv bridge.