JIT: On-disk compile cache for warm requests

[PurHur]

Problem

bin/jit.php recompiles LLVM on every invocation (~200ms+ on small scripts). bin/serve.php re-parses and recompiles each HTTP request in VM mode today; #207 would add --jit but still needs a warm cache.

Without on-disk cache, dev iteration and load tests exaggerate compile cost (#94).

Goal

Persist compiled artifacts keyed by source hash + compiler version + LLVM flags under .php-compiler-cache/ (gitignored). Second run of the same file skips parse/LLVM emit when inputs unchanged.

Implementation hints

Cache key

sha256( file_mtime | file_contents ) + COMPILER_VERSION + PHP_COMPILER_LLVM_PATH + jit flags

Store under .php-compiler-cache/<hash>/module.bc or object file path consumed by existing JIT loader.

Integration points

1. lib/Runtime.php — parseAndCompile() / JIT entry: lookup cache before Compiler + JIT::compile().
2. bin/jit.php — enable cache by default; --no-cache for debugging.
3. bin/serve.php --jit (Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207) — per-script cache dir; invalidate when mtime changes.
4. Invalidation — delete stale entries when composer.json / compiler git hash changes (embed PHP_COMPILER_BUILD_ID constant).

Measurement

• script/bench-compile.php or extend script/rebuild-examples.php with cold vs warm column.
• Target: second bin/jit.php run on examples/001-SimpleWeb >10× faster compile phase (acceptance below).

Tasks

• Define cache directory layout + .gitignore
• Serialize/load LLVM bitcode or native .so (whichever PHPLLVM supports today)
• Thread-safe file locks for concurrent serve requests
• Env PHP_COMPILER_CACHE_DIR override
• Document in README troubleshooting

Acceptance criteria

time php bin/jit.php examples/001-SimpleWeb/example.php   # cold
time php bin/jit.php examples/001-SimpleWeb/example.php   # warm: compile phase <10% cold

Verification (local / Docker only)

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  vendor/bin/phpunit --filter JITTest   # no regressions

Dependencies

• CI: Run JIT compliance tests in CI (fix LLVM skip in PHPUnit) #98 JIT compliance must execute (not 100% skipped)
• Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 serve --jit (consumer)

Files

• lib/Runtime.php, lib/JIT.php, bin/jit.php, bin/serve.php

[PurHur]

claim: cursor-agent-lane-a — starting this run

[PurHur]

Implemented on-disk MCJIT bitcode cache in PR #3842. Cross-process warm path loads .php-compiler-cache/<hash>/module.bc and skips ext/ + main IR lowering. Unit tests green; full MCJIT e2e skipped on harness where bin/jit.php segfaults (#98).