feat(system): zend_observer fcall bridge with verified per-function attach path

[lisachenko]

Implements #51 — bridges the engine's zend_observer fcall begin/end handlers to userland callbacks via System/Hook/ObserverHook, following the standard hook lifecycle and Core registry semantics.

API

Core::observeFunction(
    $function,   // zend_function* via ReflectionFunction::getRawFunctionPointer()
    fn(ExecutionData $frame) => ...,                       // begin
    fn(ExecutionData $frame, ?ReflectionValue $ret) => ..., // end (nullable — see below)
);

Empirically established engine constraints (docs/observer-hook.md has the full analysis)

• Userland can never enable the observer machinery. zend_observer_post_startup() freezes the config at the tail of module startup — before opcache.preload runs. Forcing ZEND_OBSERVER_ENABLED retroactively corrupts op_arrays sized without observer slots (verified segfault in gdb). The hook therefore requires the preload boot path AND a startup-time (MINIT) provider, and refuses with a typed ObserverException otherwise — never a silent no-op, never a memory-unsafe write.
• End handlers cannot run during exception unwinding under FFI: ext/ffi aborts in C before any PHP executes when EG(exception) is set. The end callback is therefore nullable (begin-only hooks for throwing functions), and the abort behavior is pinned by a sacrificial-child test so a future ext/ffi change surfaces.
• Lazy observer slots: attaching to a never-called function is UB in the raw engine API; install() resolves ZEND_MAP_PTR semantics (Core::mapPtrGet()), warms user-function run-time caches, and primes slots with the engine's own NOT_OBSERVED sentinel.

End-to-end verification

A 52-line test-only C provider (tests/fixtures/observer-enabler/, built on demand via phpize, cleanly skipped when the toolchain is absent) enables the machinery at MINIT while observing nothing; the firing test then asserts real begin/end events from subprocesses: simple call with return value, clean detach, nested ordering (outer-begin → inner-begin → inner-end → outer-end), exception propagation with begin-only hooks, callback-exception containment (#50), and internal-function observation (strrev). The fixture doubles as the documented reference "startup-time provider".

Generator change

Adds the zend_observer fcall symbols and zend_internal_run_time_cache_reserved_size to the FFI manifest. Host regeneration per AGENTS.md; byte-identical pre-check passed before each manifest change; engine.h delta is purely additive; layout guard green.

Verification

composer test: 265 tests / 3203 assertions OK (guard tests + preload-boundary subprocess test + firing tests). composer phpstan: level max, no errors, baseline untouched. composer cs:check: clean.

Known trade-off (documented): priming a never-called function bypasses other providers' lazy init for that function within the request — invisible with the reference enabler, an interaction to be aware of alongside a real observing extension.

Refs #51

🤖 Generated with Claude Code

https://claude.ai/code/session_01T8ixfHQ5vCoNhHYuREbm1G

---

Generated by Claude Code

[lisachenko]

Too complex and discovered restrictions makes this idea not feasible to be merged. I will keep it as a Draft for now, will decide later. Agent can stop tracking this PR, it will stay here as WIP/PoC concept only

[lisachenko]

@ezimuel looks like observer API is not possible normally from userland

[ezimuel]

@lisachenko I see, thanks for the tentative and the exploration.