Repository navigation
Description
Summary
On macOS arm64 with PHP 8.6 (Homebrew/setup-php build), installing a user opcode handler via OpCode::setHandler() on EXT_STMT (with Compiler::COMPILE_EXTENDED_STMT enabled) corrupts VM state as soon as the handler's PHP closure runs: closure bound variables read back as garbage (e.g. an int counter reads as a ZEngine\Core object), and full consumers (lisachenko/zdebug) segfault (EXC_BAD_ACCESS at 0x10 inside ZEND_DO_UCALL_SPEC_RETVAL_USED_TAILCALL_HANDLER).
The same code is green on:
- macOS arm64 + PHP 8.5 (identical probe run as control — all steps pass)
- macOS x64 (Intel) + PHP 8.6 — same PHP source build
- Linux x64 + PHP 8.6
z-engine's own CI is green on macOS arm64 + 8.6 because OpCodeHookTest hooks ADD inside a small probe function without COMPILE_EXTENDED_STMT; the corruption shows once EXT_STMT-instrumented code (compiled after the handler is installed) starts dispatching through the hook.
Why only arm64 + 8.6
PHP 8.6 introduced a new VM dispatch kind, ZEND_VM_KIND_TAILCALL (Zend/zend_vm_opcodes.h in php-8.6.0beta2):
#elif (defined(__GNUC__) && defined(HAVE_GCC_GLOBAL_REGS))
# define ZEND_VM_KIND ZEND_VM_KIND_HYBRID
#elif defined(HAVE_MUSTTAIL) && defined(HAVE_PRESERVE_NONE) && (defined(__x86_64__) || defined(_M_X64) || defined(__aarch64__)) && defined(__clang__)
# define ZEND_VM_KIND ZEND_VM_KIND_TAILCALL
#endif- Linux (gcc) and macOS x64 (clang with global register support) build the HYBRID VM — unaffected.
- macOS arm64 clang has no
HAVE_GCC_GLOBAL_REGS, so the build selects TAILCALL: opcode handlers becomeconst zend_op *(*)(zend_execute_data *, const zend_op *)with thepreserve_nonecalling convention, chained viamusttail. The crash frames (*_TAILCALL_HANDLER) confirm the failing build runs this VM.
zend_user_opcode_handlers[opline->opcode](execute_data) is still called with the classic int (*)(zend_execute_data *) signature from ZEND_USER_OPCODE_SPEC_TAILCALL_HANDLER, so the trampoline installation itself works (a trivial handler on ADD fires fine). The breakage appears when the handler re-enters PHP execution (the FFI callback runs a userland closure) while the interrupted frame's opcode came from EXT_STMT-instrumented code — pointing at an interaction between libffi callback re-entry, nested execute_ex, and the preserve_none handler chain. It may ultimately be a php-src beta bug rather than z-engine's, but z-engine is where consumers hit it, and where a repro/workaround can live.
Minimal repro (pure z-engine, no consumer code)
probe.php:
<?php
require __DIR__ . '/vendor/autoload.php';
use ZEngine\Core;
use ZEngine\System\Compiler;
use ZEngine\System\OpCode;
Core::init();
Core::$compiler->setOptions(Core::$compiler->getOptions() | Compiler::COMPILE_EXTENDED_STMT);
$fires = 0;
OpCode::setHandler(OpCode::EXT_STMT, function ($scope) use (&$fires): int {
$fires++;
return Core::ZEND_USER_OPCODE_DISPATCH;
});
require __DIR__ . '/payload.php'; // any file: a class, new, a method call, a function call
echo "EXT_STMT fires: {$fires}\n";Run with php -d ffi.enable=1 -d opcache.jit=off probe.php on macOS arm64 + PHP 8.6.0-dev:
PHP Warning: Uncaught TypeError: Cannot increment ZEngine\Core in probe.php:12
PHP Fatal error: Throwing from FFI callbacks is not allowed in payload.php on line 15
The by-ref use (&$fires) int reads back as a ZEngine\Core object on the very first handler invocation. Adding RETURN/THROW handlers fails the same way (Cannot use object of type ZEngine\Core as array on an array counter). On PHP 8.5 (same machine, same script) everything passes.
Crash signature from a full consumer (zdebug)
exception: EXC_BAD_ACCESS / SIGSEGV, KERN_INVALID_ADDRESS at 0x0000000000000010
frame 0: ZEND_DO_UCALL_SPEC_RETVAL_USED_TAILCALL_HANDLER + 116
frame 1: execute_ex + 156
frame 2: zend_execute.cold.1 / zend_execute / zend_execute_script / php_execute_script_ex
(reading offset 0x10 of a NULL zend_function, i.e. a call frame whose func was clobbered). Downstream CI evidence: lisachenko/zdebug#24 — the diagnostic job Diagnose arm64 (PHP 8.5/8.6) in run https://github.com/lisachenko/zdebug/actions/runs/33254290174 shows the layered probes (L1 Core::init ✅, L2 COMPILE_EXTENDED_STMT ✅, L3 EXT_STMT handler ❌ on 8.6 / ✅ on 8.5, L5 module registration ✅, L6 full boot ❌ SIGSEGV) plus the lldb backtrace and the macOS .ips crash report.
Suggested directions
- Reproduce with a C user opcode handler (no FFI) to split "TAILCALL VM vs user opcode handlers re-entering the VM" (a php-src bug worth reporting upstream while 8.6 is in beta) from "TAILCALL VM vs FFI callback trampolines" (z-engine-side).
- If it is php-src's: report before 8.6.0 GA; the tail-call VM is new in this cycle.
- Until resolved, consumers on Apple Silicon can be pointed at a HYBRID/CALL-VM PHP build; z-engine could also detect
ZEND_VM_KIND_TAILCALLatCore::init()(e.g. viaphp -i/Reflectionon the build metadata or a runtime probe) and fail fast with a clear message instead of corrupting the debuggee.
Activity
ci: mark the macOS arm64 + PHP 8.6 leg experimental, drop the diagnos…
fix(hook): refuse user opcode handlers on PHP 8.6's tail-call VM (#280)
lisachenko commentedon Aug 29, 2026
Root cause found — this is a php-src bug in the 8.6 tail-call VM, not a z-engine bug. z-engine now fails fast on affected builds (PR #281); below is a ready-to-file upstream report for
php/php-src(I can't open issues there from this session — please forward).Draft php-src report
Title: User opcode handlers resume execution against a stale frame under ZEND_VM_KIND_TAILCALL
Version: PHP 8.6.0beta2 / 8.6.0-dev (any build selecting
ZEND_VM_KIND_TAILCALL, i.e. clang withmusttail/preserve_nonebut withoutHAVE_GCC_GLOBAL_REGS— notably all Homebrew/macOS arm64 builds). Hybrid and call VM builds of the same source are unaffected.Summary: A user opcode handler (
zend_set_user_opcode_handler) that returnsZEND_USER_OPCODE_DISPATCHcorrupts execution when the hooked opcode executes in any frame other than the oneexecute_ex()was entered with (any function call, any include). Symptoms range from calls dispatching to the wrong function (stale run-time cache slots of the wrong frame) to SIGSEGV inZEND_DO_UCALL_SPEC_RETVAL_USED_TAILCALL_HANDLER(KERN_INVALID_ADDRESS at 0x10, i.e. a NULLzend_functionderef).Minimal repro (only ext-ffi,
php -d ffi.enable=1 -d opcache.jit=off repro.php):On hybrid/call builds:
int(3)+OK. On a TAILCALL build (macOS arm64):vm_kind=5then SIGSEGV at the first ADD insidef(). Verified on GitHub'smacos-latest(arm64, crash) vsmacos-15-intel(x64, hybrid, passes): https://github.com/lisachenko/z-engine/actions/runs/33257997984Analysis (
Zend/zend_vm_execute.has generated for 8.6.0beta2):ZEND_USER_OPCODE_SPEC_TAILCALL_HANDLER's continuation cases use the genericZEND_VM_DISPATCHmacro, which is never redefined for the tail-call section:zend_vm_get_opcode_handler_func()resolves the single-step fastcall variant (execute one op, return the next opline /ENTER_BITstate). The tail-call handler then plain-returns that value — which, because every frame transition inside the chain happened viamusttail, unwinds straight toexecute_ex(). Its loop:only refreshes its
execute_datalocal in theENTER_BITbranch. A user opcode returning DISPATCH for a normal advancing opcode yields a plain next-opline, so the loop's next iteration executes the current frame's oplines againstexecute_ex's entry frame. With mismatchedEX(run_time_cache)the very nextINIT_FCALL/DO_*CALLresolves a cached callee of the wrong frame — in our traces afwrite(STDERR, "...")in the included file executed as the outer script's cachedunlink()(unlink(): Argument #2 ($context) must be of type resource or null, string givenwith the outer file's name and the inner file's line), and object construction dispatched to an unrelated class's constructor before the SIGSEGV.ZEND_USER_OPCODE_CONTINUE/ENTER/LEAVEare unaffected (they stay on the musttail chain / go throughZEND_VM_ENTER()); DISPATCH of frame-changing opcodes survives by luck via theENTER_BITpath.Suggested fix: in the tail-call variant of the
ZEND_USER_OPCODEhandler (viazend_vm_gen.php), don't return the single-step result up the chain — resume it:(
zend_vm_call_opcode_handler()'s TAILCALL branch performs exactly this unwrap, so the same pattern applied inside the handler restores the invariant.)Supporting evidence from the diagnostics on this branch (
tools/diagnostics/issue-280/, runs on PR #281):install-onlypasses; every mode that lets the handler fire in a nested frame corrupts (probe run: https://github.com/lisachenko/z-engine/actions/runs/33256998594)EXC_BAD_ACCESS KERN_INVALID_ADDRESS at 0x10inZEND_DO_UCALL_SPEC_RETVAL_USED_TAILCALL_HANDLERGenerated by Claude Code
chore(diagnostics): make the issue #280 workflow dispatch-only
ci(diagnostics): don't let the x64 control leg fail the issue #280 run
lisachenko commentedon Oct 2, 2026
Filed upstream: php/php-src#24081 — user opcode handlers returning
ZEND_USER_OPCODE_DISPATCHmis-resume execution against a stale frame under the tail-call VM.Reference points for anyone following along:
tools/diagnostics/issue-280/pure-ffi-repro.php; latest reproduction on PHP 8.6.0-dev @dc1145e(macOS arm64,vm_kind=5, SIGSEGV) in run 36771134832; original discovery on 8.6.0-dev @ec93b0b.ZEND_VM_DISPATCHmacro,execute_ex()resume loop) is byte-identical on the PHP-8.5 branch and was already in the 8.5.0 release — 8.5 builds in the wild just don't typically selectZEND_VM_KIND_TAILCALL, so the bug stays latent there.OpCodeHook::install()guard in feat: PHP 8.6 support for user opcode hooks (tail-call VM bug diagnosed, fixed upstream) #281; once #24081 is resolved, re-dispatch theDiagnose issue 280workflow against the fixed build and the guard can be retired.Generated by Claude Code
lisachenko commentedon Oct 2, 2026
The bug affects the tail-call VM (ZEND_VM_KIND_TAILCALL) as such and has been present since the VM landed in 8.5.0 — the generated handler and execute_ex() loop are identical in PHP-8.5 and PHP-8.6. Reproduced on 8.6.0-dev builds that select the tail-call VM (vm_kind=5); 8.5 binaries in the wild are typically unaffected only because common builds don't satisfy the HAVE_MUSTTAIL/HAVE_PRESERVE_NONE selection and fall back to the CALL VM. Any 8.5 build that does select it should reproduce with the same ext-ffi script.
lisachenko commentedon Oct 4, 2026
Will be fixed once php/php-src#24109 merged. @claude We can try to use this branch to see if it fixes the bug or not. Report here the results.
feat(hook): retire the tail-call VM guard - php-src fixed the dispatch (
ci: require the macOS arm64 + PHP 8.6 leg - upstream tail-call VM bug…
docs: drop the tail-call VM bug-fix mentions from README and AGENTS
lisachenko commentedon Oct 12, 2026
Closing as resolved — the full lifecycle is complete:
ZEND_USER_OPCODE_SPEC_TAILCALL_HANDLER'sZEND_USER_OPCODE_DISPATCHcase plain-returned the single-step result up the musttail chain, resuming on a stale frame. Reported upstream as php/php-src#24081.PHP-8.6on Oct 9 (2cf7ad0), plus a test-only follow-up for arm CI (d9fb6eb5).eefe4db,vm_kind=5TAILCALL, pre-fix) reproduced the corruption on x86_64 — confirming it was never Apple-Silicon-specific — and the Oct 11 nightly (96de549, containing the fix) runs zdebug's full DBGp integration suite cleanly on the same TAILCALL build (ci: test ZDebug on the PHP 8.6 beta via z-engine 8.6.x-dev zdebug#24, now merged).Core::getVirtualMachineKind()/ theVmKindenum kept for introspection.Generated by Claude Code