deepclone_from_array: hydrate closure-bearing nodes as native lazy ghosts

On PHP 8.4+, object nodes whose payload slots carry a named-closure or
const-expr-closure marker are created as uninitialized lazy ghosts whose
hydration, closure resolution included, is deferred until the engine first
touches them. Resolving closures (fake-closure creation, attribute-args
re-evaluation) is the measurably expensive part of hydration; nodes without
such markers keep hydrating eagerly, as does everything on PHP 8.2/8.3.

Also fixes two pre-existing issues that lazy hydration would have amplified:
binding a shared &-reference to a typed declared property now registers the
property as a type source instead of tripping the engine's deref assertion,
and object-ref markers resolved against ref slots are now order-independent
by-value snapshots.

Author: nicolas-grekas

CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this extension will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- On PHP 8.4+, `deepclone_from_array()` now creates object nodes whose
+  payload slots carry a named-closure or const-expr-closure marker as
+  native lazy ghosts: all object identities (back-references, shared `&`
+  references, `===`) exist when the call returns, but those nodes' property
+  hydration, closure resolution included, is deferred until the engine
+  first touches each of them. Resolving closures (fake-closure creation,
+  attribute-args re-evaluation) is the measurably expensive part of
+  hydration, so deferral is restricted to the nodes that carry them; plain
+  value slots hydrate eagerly as before (copy-on-write makes them cheaper
+  to hydrate than to ghost), as do internal classes, `stdClass`,
+  zero-declared-property classes and `__wakeup`/`__unserialize` nodes, all
+  mixing freely with lazy ones. On PHP 8.2/8.3 everything keeps hydrating
+  eagerly. Structural validation and `$allowed_classes` enforcement
+  (including the const-expr-closure gate) remain eager; only value-level
+  resolution errors (e.g. a stale const-expr closure line, a named-closure
+  target that no longer exists) surface at first access instead of inside
+  `deepclone_from_array()`, where the engine reverts the ghost and keeps it
+  retryable. The shared hydration state lives in the new internal-only
+  `DeepClone\HydrationContext` class, which
+  `ReflectionClass::getLazyInitializer()` exposes as the initializer;
+  abandoned half-hydrated graphs are reclaimed by the cycle collector. One
+  documented deferral residue: type sources for shared `&` references bound
+  to typed properties are registered per node as it hydrates, so a write
+  through such a reference is only checked against the already-hydrated
+  holders (see README).
+
+### Fixed
+
+- Binding a shared `&` reference to a *typed* declared property aborted
+  debug builds (engine deref assertion) and skipped type-source registration
+  on release builds, so later writes through the reference bypassed the
+  property type. `deepclone_from_array()` and
+  `deepclone_hydrate(..., DEEPCLONE_HYDRATE_PRESERVE_REFS)` now mirror
+  `unserialize()`: the referenced value is verified against the property
+  type and the property is registered as a type source of the reference.
+- Resolving an object-ref marker (`true`) against a *ref id* returned either
+  an alias or a by-value snapshot of the shared slot depending on which
+  consumer resolved first. It is now always a by-value snapshot (deref
+  before copy), making the result independent of hydration order, a
+  prerequisite for lazy mode, where that order is the user's touch order.
+  Such payloads are only ever hand-crafted: `deepclone_to_array()` never
+  emits object-ref markers with negative ids.
+
 ## [0.7.2] - 2026-06-10
 
 ### Fixed

README.md

@@ -87,6 +87,68 @@ function deepclone_hydrate(object|string $object_or_class, array $vars = [], int
 (`null` = allow all, `[]` = allow none). Case-insensitive, matching
 `unserialize()`'s `allowed_classes` option.
 
+### Lazy hydration of closure-bearing nodes (PHP 8.4+)
+
+`deepclone_from_array()` creates the object nodes that are expensive to
+hydrate as
+[native lazy ghosts](https://www.php.net/manual/en/language.oop5.lazy-objects.php):
+nodes whose payload slots carry a named-closure or (PHP 8.5)
+const-expr-closure marker, since resolving those (fake-closure creation,
+attribute-args re-evaluation) is where hydration time actually goes. Every
+object identity exists when the call returns (back-references, shared `&`
+references and `===` behave exactly as for eager nodes), but a ghost's
+property hydration, closure resolution included, is deferred until the
+engine first touches it.
+
+```php
+$clone = deepclone_from_array($payload);
+// closure-bearing nodes are uninitialized ghosts; reading any property
+// of such a node hydrates that node only.
+```
+
+All other nodes hydrate eagerly: nodes without closure markers (plain value
+slots are cheaper to hydrate than to ghost, since copy-on-write makes them
+refcount bumps), internal classes (and classes inheriting one, `stdClass`
+descendants excepted), `stdClass` itself and other classes without declared
+properties, and nodes replaying `__wakeup`/`__unserialize` (their call
+order is observable and preserved). A graph without closure markers is
+hydrated fully eagerly and carries zero lazy-mode overhead, and on PHP
+older than 8.4 (no native lazy objects) everything hydrates eagerly.
+Mixing lazy and eager nodes in one graph is the normal mode of operation.
+
+Semantics of deferred nodes (the usual native lazy-object rules):
+
+- Whole-graph operations (`serialize()`, `json_encode()`, `foreach`, `==`,
+  `clone`, `var_export()`) initialize every node they visit; `var_dump()`,
+  `===`, `spl_object_id()` and `instanceof` do not initialize.
+- Structural payload errors (unknown ids, bad scopes, unknown declared
+  properties) and `$allowed_classes` violations still throw inside
+  `deepclone_from_array()`. Value-level resolution errors (a class or enum
+  case that no longer exists, a stale const-expr closure line, a type
+  mismatch) surface at first access instead; the failing ghost is rolled
+  back by the engine, stays uninitialized, and rethrows on every retry.
+- A never-initialized ghost's destructor is not called.
+- Type enforcement on a shared `&` reference is registered per node as it
+  hydrates. While some holders of the reference are still uninitialized, a
+  write through it is checked only against the already-hydrated ones; if the
+  written value violates a pending node's property type, that node's first
+  touch throws instead (eager mode rejects such a write at the assignment).
+- The payload and every object of the graph stay pinned in memory until the
+  last ghost initializes or dies; a shared `DeepClone\HydrationContext`
+  object, also returned by `ReflectionClass::getLazyInitializer()`, holds
+  them. Abandoned graphs are reclaimed by the cycle collector.
+
+Cost model, measured on 20k-node graphs (PHP 8.4, release build): creating
+ghosts instead of resolving closures cuts `deepclone_from_array()` time by
+3-5x on closure-rich nodes, and the saved work never runs at all for nodes
+that are never touched. The trade-offs apply to closure-bearing nodes only:
+a ghost that ends up touched replays all its slots then (the total cost of
+a fully traversed graph stays comparable, just paid at first touch plus the
+ghost bookkeeping), a graph dropped with uninitialized ghosts is reclaimed
+by a cycle-collector sweep instead of plain refcounting, and the payload
+plus the per-slot index stay pinned until the last ghost initializes or
+dies. Graphs without closure markers are not affected by any of this.
+
 `deepclone_hydrate()` accepts either an object to hydrate in place or a class
 name to instantiate without calling its constructor. By default, PHP `&`
 references in `$vars` are dropped on write; pass `DEEPCLONE_HYDRATE_PRESERVE_REFS`