Repository navigation
Self-host: stub surface burn-down — inventory of SelfHostBuiltinPolicy / ExternalMethod #2484
Description
Milestone
M5 stub retirement with M3/M5 diagnostic value — parent #1492 / #1520 / #1768
Problem
Self-host progress (M3→M5) requires shrinking the stub surface where PHP_COMPILER_SELFHOST_AOT=1 substitutes ExternalMethod / policy stubs for real lowering. Spine/inventory counts do not show which symbols still stub at runtime.
May 2026 harness: M3 strict emit ladder is green for trivial fixtures, but M5 driver compile fails:
./script/docker-exec.sh -- bash -lc '
source script/php-env.sh
BOOTSTRAP_M3_HELLOWORLD_STRICT=1 make bootstrap-selfhost-helloworld
PHP_COMPILER_M3_COMPILE_MODE=compile PHP_COMPILER_M3_SOURCE=bin/compile.php \
PHP_COMPILER_M3_OUT=/tmp/out ./build/selfhost-helloworld-emit
'
# parseAndCompile returned null — likely stubbed Runtime init / parse spine (#2633)A generated stub inventory helps implementers pick the next symbols to real-lower without grep archaeology.
Scope (implementation = audit script + generated docs)
| Path | Role |
|---|---|
script/bootstrap-selfhost-stub-inventory.php |
New — scan + --check |
lib/JIT/SelfHostBuiltinPolicy.php |
Policy categories / isRequiredForBundle |
lib/JIT.php |
shouldUseM3EmitTuRuntimeMethodStub(), ExternalMethod, selfhost skip patterns |
lib/Func/Internal.php |
Internal builtin dispatch |
docs/bootstrap-selfhost-stubs.md |
Generated markdown |
docs/bootstrap-selfhost-stubs.json |
Generated JSON (optional CI snapshot) |
Repro (today: manual)
# Partial stdlib JIT audit (not AOT-specific):
php script/audit-stdlib-jit.php
# M3 emit-TU runtime method stubs (high leverage for #2633):
grep -n 'shouldUseM3EmitTuRuntimeMethodStub\|M3EmitTuRuntimeMethodStub\|compileRuntimeInit' lib/JIT.php | head -40
# Self-host env sites:
grep -rn 'PHP_COMPILER_SELFHOST_AOT' lib/JIT.php lib/Func/ lib/JIT/SelfHostBuiltinPolicy.php | wc -l
# Tie stubs to M5 failure:
./script/docker-exec.sh -- bash -lc '
source script/php-env.sh
BOOTSTRAP_M3_HELLOWORLD_STRICT=1 make bootstrap-selfhost-helloworld
PHP_COMPILER_M3_SOURCE=bin/compile.php PHP_COMPILER_M3_OUT=/tmp/out \
PHP_COMPILER_M3_COMPILE_MODE=compile ./build/selfhost-helloworld-emit
'Done when
-
php script/bootstrap-selfhost-stub-inventory.phpwrites stable JSON + markdown - Each entry: symbol name, stub kind, file:line, category, suggested issue when known (Self-host M5: native emit bin/compile.php fails — parseAndCompile returned null #2633, M2/M5: Retire PHP_COMPILER_SELFHOST_AOT stubs on Compiler compile spine #1520)
-
./script/docker-exec.sh -- bash -lc 'php script/bootstrap-selfhost-stub-inventory.php --check'exits 0 - Linked from
docs/bootstrap-selfhost.mdand Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 stub-burn-down row
Non-goals
- Removing stubs in this issue (M2/M5: Retire PHP_COMPILER_SELFHOST_AOT stubs on Compiler compile spine #1520, Self-host M3: compile-driver real lowering symbol batch tracker #1768, Self-host M5: native emit bin/compile.php fails — parseAndCompile returned null #2633)
- CI default-on gate (follow-up after snapshot stable)
Activity
PurHur commentedon May 26, 2026
Backlog architect (May 2026): Parked until M3 emit-TU is green (#2512, #2513, #2540). Stub burn-down is valuable but does not unblock red bootstrap gates. Revisit after #2442 closes. Epic: #1492.
PurHur commentedon May 27, 2026
Status update from a fresh self-host run (2026-05-27, master, Docker): M2/M3/M4 slice gates are green, and the next hard blocker is M5 vendor prelink AOT (--compile).
Repro:
./script/docker-exec.sh -- bash -lc 'make north-star5-verify'First failing symptoms are vendor-prelink compile failures (object_ok is currently 0/3):
Unknown type declaration found: */atvendor/ircmaxell/php-types/lib/PHPTypes/Type.php:443PhpParser\Error: unexpected T_USEduringircmaxell/php-llvmbundle compileNew focused blockers filed:
This makes the stub-inventory idea even higher leverage: once vendor prelink starts compiling, we’ll need a fast way to see which remaining
PHP_COMPILER_SELFHOST_AOTstubs are still masking real lowering gaps on the M5 cold-boot path.