feat(parallel): accept capacity 0 on a shared channel as a real rendezvous

[lisachenko]

Closes #14, via Option 1 — the substrate exposes a named API for registering a non-spinning waiter (lisachenko/php-shared-data-extension#26), and this runtime rides it. Depends on that PR; CI here is red until it merges into substrate main (this package requires it as dev-main) — expected, with precedent.

What works now

declareShared('x', SharedChannel::class, capacity: 0) is accepted. A cross-process rendezvous behaves like the local one: send() returns only once a receiver in another process has taken the value, a receiver parks until a sender arrives, and both sides park on their own poller — nobody spins.

• SharedChannel registers this process with the substrate while any local coroutine waits to receive, and withdraws when the last one leaves. The registration is derived from the waiter list rather than counted — a drifting count is the stale-registration bug, so there is nothing to drift.
• A rendezvous send() deposits its record (only possible while a partner is registered), then parks a second time on the ticket until isTicketTaken() says the handshake completed. Waiting for the take rather than the deposit is what keeps cancellation sound: a receiver that cancels after a deposit leaves the record in the ring for the next receiver, and the sender keeps waiting — nothing lost, nothing double-delivered.
• Channel waiter tables are sized to the wake-registry slot count, so a registration can never be refused for a family the notification plane can serve.
• serve() skips the currently-running coroutine — it is on its way into a park and has not suspended, so unparking it would strand a claimed select token. Only another process can change state in that window, and its wake event is already in our socket.

One narrower refusal replaces the blanket one

A capacity-0 shared channel cannot be a select send case. A select case must resolve without parking, and the deposit is the only non-parking moment — one step too early to promise a take. Claiming there would silently give that one case buffered semantics while send() on the same channel keeps rendezvous ones. It throws with both remedies named (a capacity-1 channel, or a plain send()). Receive cases compose in Select normally, alongside local channels.

Acceptance criteria from #14

• ☑ declareShared(..., capacity: 0) accepted — testACapacityZeroSharedChannelIsAccepted.phpt
• ☑ Send blocks until another process takes the value — testARendezvousSendWaitsUntilAnotherProcessTakesTheValue.phpt: the worker registers, then holds its scheduler in a call-free loop for 400 ms so the deposit is possible but the take is not; the parent's clock starts only after hasWaitingReceiver(), so what is measured is the take alone.
• ☑ Receiver parks until a sender arrives — testARendezvousReceiverParksUntilASenderArrives.phpt
• ☑ Neither side spins, asserted by counting — testACapacityZeroHandoffCostsABoundedNumberOfWakeupsOnBothSides.phpt: 8 handoffs, both processes counted, bound 64, measured 9 and 14.
• ☑ Composes in a Select with a local channel — testACapacityZeroSharedChannelComposesInASelectWithALocalChannel.phpt
• ☑ No stale registration after a Select loser or cancelled context — testASelectLoserLeavesNoRendezvousRegistrationForALaterSend.phpt, testACancelledContextWithdrawsItsRendezvousRegistration.phpt — both probe the shared count from another process.
• ☑ Deadlock detection treats the wait as externally wakeable — testARendezvousWaitIsNeverAFalseDeadlock.phpt

Plus the refusal (testASelectSendCaseOnACapacityZeroSharedChannelIsRefused.phpt), the no-socket single-process path (testTwoCoroutinesOfOneProcessRendezvousOnASharedChannel.phpt), and an interaction test with the freshly-merged slot recycling: testASlotIsRecycledWhileARendezvousSendIsStillParkedOnItsTicket.phpt — the two structures are disjoint and share only the process's wake socket, so a slot event costs a parked rendezvous sender one spurious re-check and nothing more.

Verification

PHP 8.4, -d ffi.enable=1 -d opcache.jit=off, against the exact tree the substrate PR produces (merged branch synced into vendor):

suite      OK (121 tests, 121 assertions), 3/3 repeats identical
phpstan    level max, no errors
cs:check   clean
soaks      arena-watermark PASS (slots plateau at 1 record; watermark/allocated/rss +0.0 KiB)
           memory-flatness PASS · no-leftover-children PASS · preemption PASS
           --self-test and --leak-slots both still FAIL as required

Known limits, stated: the runtime registers receivers but not senders (sender wakeups ride the family broadcast, per the documented design) — a mixed family with a plain-substrate taker would need the sender registration the substrate already provides; and the select-send refusal fires when the select actually parks on the case, not at declaration.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U5QRWPfmkZME7hDjU6i5EA

---

Generated by Claude Code