feat: boot from Composer's autoloader (closes #21), plus ClassSpecializer::evict() and Core::sizeOfType()

[lisachenko]

Why

An audit of userland-php-generics (the reference consumer) found it reaching behind z-engine's API line for operations that had no named entry point: probing isset(Core::$executor) to ask "is the engine booted", deleting class-table buckets through the @internal HashTable::delete(), pairing Core::sizeof(Core::type(...)) so a raw FFI\CType crossed the boundary, and re-deriving "can the engine run here" from ini_get('ffi.enable').

Review feedback then pointed at the better fix for most of that: don't make consumers initialize the engine at all.

Closes #21 — automatic initialization via Composer

bootstrap.php, registered through autoload.files, boots the bridge. require vendor/autoload.php is now the whole boot for every consumer.

Issue #21 has been open since 2019 on one blocker, recorded in its own comments: "Preloading breaks all the things — because composer autoloader calls the Core::init() before preload initialization." That is real. An unconditional boot binds the definitions with FFI::cdef(), which lasts for the preload request only, and leaves an engine behind that turns the script's own Core::preload() into a no-op — so the server starts and every request after it fails.

So the bootstrap recognises the preload stage and serves it with Core::preload(), whose FFI::load() publishes the definitions under FFI_SCOPE for the life of the server; everything else gets Core::init(). The stage is identified by the one fact that distinguishes it: during preloading, the script named by opcache.preload is the first file the process included.

Verified end to end on a matching PHP line, not just asserted:

preload via autoloader  → FFI::scope('ZEngine') resolves in the next request   ✅
preload skipping the boot → "Failed loading scope 'ZEngine'"                    ✅ (control)

Core::preload() is now idempotent too, so the explicit call an existing opcache.preload script makes right after requiring the autoloader stays harmless.

Failure is silent, and explained where it matters

A host without ext-ffi, with ffi.enable=0, on an unsupported PHP minor or platform can still legitimately autoload this package — static analysis, FFI-disabled test jobs, composer-time tooling. Throwing from an autoloaded file breaks all of them at require, so the boot is left undone in silence. Nothing is lost: Core::init() is idempotent, so code that needs the engine calls it and gets the same explanatory RuntimeException the bootstrap swallowed. ZENGINE_AUTOBOOT=0 skips the boot entirely.

Note z-engine's own test bootstrap deliberately still calls Core::init() explicitly — every test here drives the engine, so an unsupported host has to say so once rather than through hundreds of confusing failures. AutoBootTest proves the automatic path in child processes, where it can be observed without that line interfering.

Also in this PR

• ClassSpecializer::evict(string $className): bool — the destroying counterpart of specialize(): removes the class-table bucket so destroy_zend_class() dismantles the entry now, while op_array-refcounted bodies shared with the source stay alive. Reads the class through ReflectionClass::isUserDefined()/isImmutable()/isPreloaded() — no ce_flags from the outside. ReflectionClass::isPreloaded() is added beside isImmutable().
• Core::sizeOfType(string $type): int — the named form of the sizeof(type(...)) pair; Core::type() is now @internal, so no raw CType crosses the API line.
• AGENTS.md — the @internal / FFI-CData rule for dependent packages folded into Public APIs never leak CData.

Deliberately no ReflectionClass::evict() mirror: an instance method destroying the entry its own wrapper points at invites use-after-free on $this->pointer.

Review comments

All four addressed in b1c0b92 — Core::isUsable() dropped (the bootstrap removed the need for it rather than relocating it), evict() moved onto the reflection API, AGENTS.md section folded. Replies are on the threads.

Notes for review

• Consumer counterpart: refactor: consume z-engine through its documented API only (audit follow-up) userland-php-generics#14 (same branch name), which now boots nothing at all.
• Per the branch model this should merge up to master so the 8.5 line carries the same API and bootstrap.
• Verified on this container (PHP 8.5): phpstan and php-cs-fixer green; auto-boot, opt-out, silent-failure and the preload→request path each exercised directly. The suite itself needs a PHP 8.4 host for this line — covered by CI.
• c8c8dfa skips the two preload cases on Windows, where PHP has no preloading at all (issue feat(opcache): macOS/arm64 & Windows support for the relocator (absolute-address oplines) #119).

🤖 Generated with Claude Code

https://claude.ai/code/session_019TGQqR7ByjHrVSYKVHPrkJ