F: Layer P integration — shared roots, shared channels, result slots, JoinHandle

[lisachenko]

Part of #1. Plan: artifact.

The glue that turns the substrate primitives into the package's public parallel API. This ticket writes no shared-memory machinery of its own — the arena, rings, slots and locks come from the extension; this is the PHP-side runtime that drives them and makes them selectable alongside local channels.

⛔ Blocked on lisachenko/php-shared-data-extension#16 (E1 — arena, arena-backed persist) and lisachenko/php-shared-data-extension#18 (E3 — SharedChannel, SharedArray, result slots, event-record notification protocol). Everything else in #1 is independent of the substrate; only this ticket waits.

For local development against unmerged substrate work, pin the extension to dev-claude/php-coroutines-plan-5vovsz in composer.json and mark the temporary pin in the PR body. The pin must be removed before the milestone is undrafted.

✅ The premise is validated

The substrate spikes (ext#15) ran 84/84 green on PHP 8.4.19 and 8.5.9: an engine-formatted zend_object in MAP_SHARED|MAP_ANONYMOUS memory attaches as an ordinary PHP instance in several forked processes at once, and a plain $obj->prop = ... in one is visible to the others within ~200 µs. The reverse direction works too — a child bump-allocates and persists post-fork, sends 8 bytes, and the parent attaches. Zero-copy cross-process objects are real; this ticket is glue, not a gamble.

Binding corrections from those spikes

These are acceptance criteria, not advice. They come from measured failures, and each one is a defect that would otherwise be found in production rather than in review.

1. A 16-byte record is not read atomically. ~1.3 % of unlocked reads saw payload and tag from different generations. Every record in an arena ring or result slot is therefore either accessed wholly under the slot's mutex, or published payload-first-tag-last and read tag-first-payload-second, with the tag as the publication flag. Never a mix of the two disciplines. (The control socket is unaffected — an ordered byte stream cannot tear.)
2. An aligned 8-byte pointer read is atomic. A single-slot OBJ/STR/ARR address read whose tag cannot change may skip the lock and get old-or-new, never a mix. Do not over-lock the hot read path in await().
3. Never var_dump(), json_encode(), get_object_vars() or (array) a shared object unless the extension's get_properties_for interception is active. Those read-shaped operations make engine C code write a per-process properties pointer into the shared struct, segfaulting every sibling afterwards. This binds the runtime's own diagnostics hardest: a panic path or debug dump is exactly the code that reaches for var_dump() on the value it is reporting.
4. Never key a shared object by spl_object_id(), and never put one in an SplObjectStorage. Forked children inherit the same object-store free list and hand out identical handle numbers — handles collide by construction. Arena address is the only cross-process identity, and spl_object_id() on a shared object needs a documented story rather than an assumption.
5. Closures are rejected on provenance — compiled before the fork barrier — never on shape. A post-fork closure cannot be recognised by inspection: a stale address held a different, perfectly valid Closure that on PHP 8.5 executed the wrong function instead of failing. Any check that inspects bound variables, scope or arity will pass that case.
6. A worker that dies holding an arena lock surfaces EOWNERDEAD. The extension handles recovery, but this ticket must make sure the resulting failure reaches the waiter as a WorkerCrashedException rather than a silent hang, and that a recovered-but-inconsistent slot is not read as if it were valid.

Scope

• Named shared roots — declareShared(string $name, string $class, int $capacity) at configuration time, shared(string $name) for lookup. Roots are created pre-fork so every worker inherits them by address; declaring a root after run() has forked is an error with a message that says so.
• persist() / attach flow — $runtime->persist($obj) clones a graph into the arena and hands back the shared instance. Attaching in a worker is by address, through the extension's per-process side table; the package must never cache an arena address across a fork boundary in a way that assumes the parent's per-process state.
• SharedChannel integration — expose the substrate ring through ChannelInterface so it drops into the existing Select unchanged. readinessFd() returns the worker's wake-pipe FD; the poller must drain the wake pipe on readiness (level-triggered pokes: spurious wakeups are harmless, lost wakeups impossible, but an undrained pipe spins the poller).
• Result slots + JoinHandle::await() — spawnParallel() allocates a slot, returns a handle; await() parks the calling coroutine on the pipe FD via the poller, wakes on the RESULT record, and reads the value directly from shared memory. Awaiting an already-complete slot returns immediately without parking; a slot may be awaited from any process.
• Panic path — an uncaught Throwable in a parallel task completes its slot as PANIC with the address of a shared error-info object (class, message, trace as arena strings), rethrown at await() as ParallelTaskException preserving that information. The NSR applies here too: the panic must not be serialized to cross the boundary — and per correction 3, the path that builds it must not var_dump() the offending value.
• NotShareableValueException — thrown when a value cannot cross a boundary (plain array, closure, resource, non-shared object). The message must name the remedy: $runtime->persist($obj), use SharedArray, implement Task.
• Version-gate on the substrate's LAYOUT_VERSION 4 and fail fast with a clear message on mismatch.

Acceptance criteria

• A worker mutates a shared object and the parent observes the mutation on the same identity — zero-copy, no re-read from any encoding.
• spawnParallel → await() returns each tag correctly: NIL/TRUE/FALSE, INT, FLOAT, STR (arena string), OBJ (shared object), ARR (SharedArray).
• await() on an already-completed slot does not park; await() from a different process than the spawner works.
• Slot publication order is asserted, not assumed: a test that writes a slot and reads it concurrently under contention must never observe a tag newer than its payload.
• No var_dump/json_encode/get_object_vars/(array) on a shared object anywhere in the shipped source — enforced by a source check, including the panic and diagnostic paths.
• No spl_object_id()/SplObjectStorage keying of shared objects — enforced the same way.
• A SharedChannel and a local Channel in a single Select both fire, and the shared one wakes the poller through its readiness FD.
• The wake pipe is drained — a test asserts the poller does not spin (bounded wakeups for a bounded number of sends).
• Task panic surfaces as ParallelTaskException with class, message and trace intact.
• A worker killed while holding an arena lock surfaces WorkerCrashedException at the waiter — no hang, no silently-consumed inconsistent slot.
• NotShareableValueException for a plain array, a closure, a resource and a non-shared object — each message naming its remedy; the closure case documented as provenance-based.
• No serialize/igbinary/json_encode anywhere on the data path — enforced by a test that greps the shipped source, so a regression fails CI rather than review.
• A coroutine blocked on a shared primitive or an outstanding JoinHandle is not reported by DeadlockException (externally wakeable — see A: local scheduler — run queue, timers, poller, deadlock detection #3).
• Soak: arena watermark plateaus (no unbounded growth), memory flat, zero leftover children.

[lisachenko]

⚠️ Blocker to resolve when wiring the pool: the preemption seam does not compose

#5 and #6 were built in parallel and their seams do not fit as they stand. This ticket does the real wiring, so the fix belongs here. Recording it precisely so it is not rediscovered by watching workers silently fail to be preempted.

The mismatch

ProcessWorker::runChild() invokes the $afterFork closure before WorkerChild::main() creates the child's scheduler — deliberately, since the closure exists to re-arm the interval timer that fork clears, and that must happen before any fiber exists.

But Preemptor::__construct() takes a Scheduler, and Preemptor::shouldPreempt() answers by consulting $this->scheduler->current(). So neither available option works:

1. Construct a Preemptor inside $afterFork — impossible, the child's scheduler does not exist at that point.
2. Call the inherited parent Preemptor's rearmAfterFork() — the timer is armed correctly, but the bridge stays bound to the child's copy of the parent's Scheduler object. current() on that copy never returns the coroutine the child's real scheduler is running, so shouldPreempt() returns false forever and the child is never preempted, silently.

Option 2 is the trap, because it looks right and fails quietly — the same silent-failure mode ItimerClock's docblock warns about, reached by a different route.

What the fix probably looks like

Not prescribing a design, but the shape is constrained:

• The timer is a process-global concern (ItimerClock::rearmAfterFork()) and is separable from the scheduler binding. Re-arming the clock in $afterFork is correct and should stay there.
• The Preemptor must be constructed against the child's own scheduler, which means after WorkerChild::main() builds it. That needs either a second seam inside WorkerChild, or $afterFork widened to \Closure(int, SchedulerInterface): void and moved after scheduler construction — but then it no longer runs before fibers exist, which was the point of its current placement. Splitting it into two callbacks (pre-scheduler clock re-arm, post-scheduler preemptor attach) is the option that preserves both invariants.
• Whatever is chosen, Scheduler::attachPreemptor() already exists, so the child's scheduler can be given a preemptor after construction.

Acceptance criterion to add

• A worker in a preemptive pool is provably preempted: a call-free loop inside a task does not starve another coroutine in that worker. A test asserting only that the timer is armed would pass under the broken wiring above and must not be considered sufficient.

Nothing on main is affected today — Runtime::spawnParallel() still refuses with this ticket's LogicException, so the combination is unreachable from the public API. Found by smoke-testing the wiring during the #12 integration; the signatures are type-compatible, which is exactly why the mismatch is semantic rather than something the type checker would catch.

---

Generated by Claude Code

[lisachenko]

✅ Unblocked — the substrate is merged, and it changes three things in this ticket

lisachenko/php-shared-data-extension#21 (E1 arena + E2 mutable mode + E3 IPC primitives) and lisachenko/php-shared-data-extension#22 (E4 AGENTS.md + E5 Phase A closures) are both merged to that repo's main. Everything this ticket was waiting for exists, so no temporary composer pin is needed — depend on the released line, not on dev-claude/php-coroutines-plan-5vovsz.

1. The event record is theirs, not ours — ControlRecord must change

I committed on lisachenko/php-shared-data-extension#15 that if E3's wire shapes differed, this package would follow. They differ. The substrate's notification record is 16 bytes:

  0  uint8  opcode    WAKE | RESULT | PANIC | CLOSE
  1  uint8  tag       ValueTag of what became available
  2  uint16 padding
  4  uint32 id        channel / slot id
  8  uint64 address   arena address, and 0 unless the tag is address-shaped

Our ControlRecord is 32 bytes (opcode | 7 pad | uint64 slot_id | 16-byte TaggedRecord). The substrate's layout wins on anything crossing into shared memory or its wake sockets. Whether our own parent↔worker control socket (#6, ProcessWorker/ControlSocket) also converts is a judgement call for this ticket — one record shape everywhere is simpler and worth it unless there is a concrete reason to keep two.

TaggedRecord (16 bytes, uint8 tag | 7 pad | uint64 payload) still matches their value record, so that half is already aligned.

2. LAYOUT_VERSION is 5, not 4

The ticket body says version-gate on 4. E1 took it to 4 (arena tables) and E2 to 5 (the per-object role). Gate on 5 and hard-fail on mismatch.

Also check our Tag enum against their ValueTag numerically, not just by name: they append Closure = 9 and state that tag numbers are the wire contract of this runtime and are never renumbered. If NIL=0 … CLOSE=8 does not match theirs exactly, ours changes.

3. Closures are now shareable — and Task is no longer the only option

E5 Phase A landed registerSharedClosure($name, $closure) before a markForkBarrier(), with acceptance by provenance (a pre-fork register), never by shape — exactly as correction #8 requires. Captures are validated at registration: use (&$ref) and static $n inside the body are refused, as are plain arrays and request objects.

So NotShareableValueException::forClosure()'s message should now name registerSharedClosure() as the remedy rather than only pointing at Task. Post-fork closures stay refused, and Phase B (arena-cloned op_arrays) is documented but not implemented.

4. What we get to build on

• Shm\Arena (pre-fork mmap, robust pshared mutex bank, roots directory), PersistentStore::bootShared($arena), persist($key, $obj, mutable: true), mutableHandle() for the synchronized write path.
• Ipc\SharedChannel (capacity-0 rendezvous crosses processes; close() crosses processes), SharedArray, ResultSlotTable (allocateSlot/complete/completePanic/readSlot/await), SharedError, SharedMutex, AtomicInt, SharedWaitGroup, WakeRegistry.
• notificationStream() on every primitive — that is precisely ChannelInterface::readinessFd(). Their blocking helpers are a spin loop and they say outright that "parking a Fiber is deliberately not in this package" and belongs to the consumer runtime. That is this ticket.
• sharedIdOf($obj) is the identity, returning the arena address. spl_object_id() reads a deliberate sentinel and is meaningless — matching correction B: local channels, select, sync primitives, context #4 already recorded above.

5. Constraints their limits section adds to ours

• Classes must be loaded before the fork — a shared clone carries one ce for the whole family. Our prefork ordering gains a step.
• The wake registry must be created before any fork, same as the arena and roots.
• A direct $obj->prop = ... is unsynchronized; the synchronized path is mutableHandle(). Our docs should not show a bare property write on a shared object as the happy path.
• One SharedError per store — a second panic replaces the first. That bounds what ParallelTaskException can promise when several tasks panic; say so rather than implying every panic is preserved.
• Rewriting a string property N times costs N arena blocks (leak-until-teardown), which is what the arena-watermark soak must tolerate: a plateau under steady state, not zero growth.

Still required, unchanged

The preemption-seam blocker from the previous comment stands and is part of this ticket.

---

Generated by Claude Code