feat(memory): allocator seam for persistent cloning + external arData install (closes #223)

[lisachenko]

What this changes

Closes #223 (PR-Z1 of the zero-serialization PHP coroutines initiative).

Today every persistent byte z-engine mints funnels through a hardcoded Core::trackedNew(..., persistent) — FFI's pemalloc, i.e. the process-local heap. A consumer that keeps real PHP objects in a fork-shared mmap arena (lisachenko/php-shared-data-extension, EPIC lisachenko/php-shared-data-extension#15) cannot redirect that, and a table the engine grows on its own drags half of itself back into process-local memory. This PR opens both seams and removes the reach-throughs that consumer needed.

1. Allocator seam. ZEngine\Memory\Allocator hands out addresses of zeroed, aligned blocks and reports whether it keeps ownership of them. EngineAllocator is the default implementation and reproduces the three allocation shapes the framework used to hardcode — trackedPersistent(), trackedRequest(), persistent() (untracked). An optional allocator is threaded through:

• PersistentObjectFactory::persistentClone($object, ?Allocator)
• StringEntry::persistent() / persistentInterned()
• HashTable::__construct(?Allocator) (inherited by PersistentHashTable)
• PersistentGraphCloner::__construct(?Allocator) — one allocator for a whole graph

Null keeps each primitive on its own historical default, which is deliberately not the same allocator for all of them (object clones and table structs stay tracked malloc blocks, string blocks stay untracked ones). Zero behavior change for existing callers; no existing test needed a line changed.

2. External arData install. PersistentHashTable::installExternalStorage($address, $capacity) writes the engine's own zend_hash_real_init_mixed layout over a caller-allocated block — HT_SIZE_EX sizing via externalStorageSize(), hash part of two uint32_t slots per bucket reset to HT_INVALID_IDX, buckets right behind it, HASH_FLAG_UNINITIALIZED replaced by HASH_FLAG_STATIC_KEYS while the iterator count is left alone. Installation is only legal before the first insert, so the engine never real-initializes storage of its own. withExternalStorage() pairs it with the struct allocator in one call.

Growth is guarded from both sides, since the engine grows a full table by pereallocing exactly that block:

• prevention: inserts through the wrapper refuse the write that would trigger the resize (getRemainingCapacity() reports the headroom; an upsert of an existing key consumes no slot and stays allowed at full capacity);
• detection: assertNoGrowth() verifies arData/capacity are still the installed ones — for engine paths this class cannot intercept — and runs after every insert.

destroy() refuses on both foreign-allocated structs and installed external storage: zend_hash_destroy() would pefree the caller's block and the struct free assumes z-engine's allocator.

3. Public-API remedies for the @internal / Core::$executor reach-throughs in php-shared-data-extension:

Reach-through today	Named public method
Core::$executor->objectStore->put($cdata)	ObjectEntry::register(): int
Core::$executor->objectStore->recycle($handle)	ObjectEntry::unregister(): void
Core::$executor->classTable->find(strtolower($n))	ReflectionClass::fromClassTable(string): ?ReflectionClass (no autoload, null on miss)
Core::type($t)->getStructFieldOffset($f)	Core::offsetOfField(string $type, string $field): int
Core::sizeof(Core::type('zval'))	already covered by Core::sizeOfType()

Store registration is encapsulated on the object that is being registered (review feedback, f8a4ab5): register() returns the handle the engine assigned, unregister() reads the handle at call time, verifies the slot actually holds this object and returns it to the free list — a stale handle is refused with a named domain exception instead of detaching somebody else's object. ObjectStore itself is unchanged by this PR; put()/recycle() stay @internal and a consumer never sees EG(objects_store) at all.

Design notes

• No CData crosses a public boundary. The allocator interface is integers only (allocate(int $size, int $alignment = 16): int), so an arena implementation in a consumer package binds its own mmap/pthread primitives with FFI::cdef (precedent: Core::persistentFree()'s Windows cdef) and returns the address it computed. installExternalStorage() takes an address; ObjectEntry::register()/unregister() take and return nothing but an int handle. Blocks are converted to typed handles inside the owning classes.
• Ownership is explicit, not guessed. Allocator::ownsAllocations() is what a structure consults before any release path; a table on foreign memory throws TypeOperationException instead of calling free(3) on somebody else's arena.
• Engine structures stay owned by their type class. All HT_SIZE_EX/HT_SIZE_TO_MASK/HT_HASH_RESET arithmetic lives inside PersistentHashTable, and the store bookkeeping of an object lives on ObjectEntry; callers pass capacities and handles, never offsets or store views.
• Generated headers untouched — no include/, stubs/ or .phpstorm.meta.php change; no new engine symbol was needed (HASH_FLAG_STATIC_KEYS, HT_MIN_SIZE and friends are already generated constants).
• Domain exceptions via named constructors — eight new factories on TypeOperationException, plus a new AllocationException.
• Not in scope: PersistentHeap::put() still uses the default allocator. Its eviction path frees blocks through z-engine's own allocator, so accepting a foreign one there needs a matching release contract — a follow-up, not a silent half-measure.

Test evidence

composer test                 497 tests, 5095 assertions — OK (5 skipped, 5 incomplete)   [462 before]
phpunit --group internal      161 tests,  480 assertions — OK (process-isolated, no crash)
composer phpstan              [OK] No errors  (level max, no new baseline entries)
composer cs:check             [OK]            (PER-CS2.0)

New coverage: tests/Memory/EngineAllocatorTest.php (zeroing, alignment guarantees per mode, registry membership, refusals), tests/Memory/AllocatorSeamTest.php (clones/strings/tables/whole cyclic graphs land in an arena-shaped test allocator; defaults keep the historical allocation classes), tests/Type/PersistentHashTableExternalStorageTest.php (layout math, lookups through installed storage, capacity guard, upsert at full capacity, relocation diagnosis, install-after-init and destroy refusals, struct+storage both in one region), tests/Type/ObjectEntryRegistrationTest.php (handle assignment and engine visibility via spl_object_id, slot returned without touching the object, re-registration, both refusal paths), plus fromClassTable()/offsetOfField() cases in the existing Reflection/Core tests.

Environment it was verified on

• PHP version (full first line of php -v): PHP 8.4.19 (cli) (built: Mar 30 2026 19:28:35) (NTS)
• Thread safety: NTS
• OS / architecture: Linux / x86_64
• Debug build (--enable-debug)? no

Checklist

• Targets the minimum affected version branch (8.4) — merges up to master per branch flow
• composer test passes on the matching PHP minor
• composer phpstan (level max) and composer cs:check are green
• Tests added or updated; no new struct dereference needed (HashTable/Bucket are already in layout_structs)
• tools/generator/symbols.php unchanged — nothing under include/, stubs/ or .phpstorm.meta.php was touched
• Conventional Commits used for the commit messages

🤖 Generated with Claude Code

https://claude.ai/code/session_01B9xaBchjdo1atarNZ6sZqe