feat(parallel): give result slots back once their handle has taken the answer

[lisachenko]

Closes #16. Consumer half of the recycling work; depends on lisachenko/php-shared-data-extension#25. This package requires the substrate as dev-main, so CI here stays red until that lands on substrate main — expected, with precedent in this repo.

What it adds

The substrate now recycles result slots through a generation-tagged free list. This PR is the signal that says a slot has been read — and the audit that says when saying so is true.

When it is safe. SlotTable::settle() is the only place this package reads a shared slot record, and it copies the whole outcome into per-process state before returning: the decoded value, or a ParallelTaskException built from the shared error object's named properties. After that nothing here looks at shared memory for that slot again — refresh() skips locally complete slots, and failPendingOf() reaches the record only through refresh(). So JoinHandle takes its answer out of the slot, keeps it, and only then releases: capture, then release. Awaiting the same handle again replays what was kept.

What came out of the record stays valid: an OBJ/STR answer is an arena address and the arena frees nothing, so releasing a slot returns the slot record, never the memory the answer lives in. Same for a panic's SharedError — the strings the exception carries are arena strings that outlive any slot. No error-graph reclamation is attempted, and none should be from a worker: children never free arena memory, so those stay leak-until-teardown (#19's ground).

One counter, two lifecycles

This lands on top of #29, which counted claims to decide when to drop a slot's local view, while this branch counted handles to decide when to give the shared record back — two mechanisms measuring the same thing. They are now one counter, ResultSlot::$claims, and forgetIfSettled() is the single decision: at zero claims on a settled, unwaited-on slot the local view is dropped always, whatever this process's role, while the shared record goes back only if this process owns it and the family really settled it. An adopter drops its view and releases nothing; a slot whose worker died drops its view and keeps its record out of circulation, because that record is still pending where a zombie may write to it. Pending slots are never forgotten whatever the claim count — failPendingOf() must still find them.

JoinHandle gives its one claim back at the first of two moments — awaited, or collected — guarded so the pair cannot count as two (attachResult() of a slot this process opened is legitimately two handles on one slot). Awaiting releases immediately, which is strictly stronger than release-at-collection: a batch that spawns N and awaits in a loop holds one slot at the end, not N.

A settled, never-awaited handle recycles its record and discards the answer, deliberately. Keeping it is the exhaustion bug itself for fire-and-forget code, and nothing is silently misled — a sibling holding the id gets a generation refusal, not the next task's result. Dropping a handle whose task is still pending keeps the slot until it settles.

Merging the two mechanisms surfaced a real bug that main's own suite caught: #29's settle() ends by forgetting an unheld slot, and this branch's adopt() settles eagerly to refuse a stale ticket at attach time — so adopting an already-settled slot forgot the view before the caller's claim was counted. adopt() now claims before it settles, with the ordering written down at the call site.

Cross-process semantics, stated plainly: the owner releases; an adopter in another process must finish reading before the owner's await() returns, or its next read is refused by generation — loudly, never with another task's result. A shared reader count in the slot record is the alternative if unordered multi-process readers ever become a real workload.

Option 2 as well

new Runtime(..., slots: N) sizes the table, and the README gains a result-slot budget section: one slot per spawn, given back at await(), so the supply bounds concurrency rather than throughput — with the arithmetic and the two exceptions spelled out.

Acceptance criteria from #16

• ☑ A pool spawning far more tasks than the slot supply runs to completion — testAPoolOutlivesItsResultSlotSupply.phpt: 8 slots, 100 tasks, 1 slot record ever created, 0 outstanding, 99 recycled.
• ☑ A handle on a recycled slot id fails loudly — testAHandleOnARecycledSlotIsRefusedRatherThanAnsweredWithAnotherTasksResult.phpt: await task A, spawn B onto the same record, attachResult() A's id, assert the refusal names the slot and both generations and that B is unharmed.
• ☑ soak-arena-watermark.php shows slot consumption plateauing — new slots series with a zero-tolerance plateau verdict; the tool now runs on a deliberately small table (--slots=64, 320 spawns) because a table big enough to absorb the run would prove nothing. --leak-slots makes the new detector fail on demand, as --self-test does for the watermark.

Plus testAnUnawaitedHandleGivesItsSlotBackWhenItIsCollected.phpt on a one-slot table, where the second spawn can only be allocated if the dropped handle's record really came back.

Verification

Against the exact tree the substrate PR produces (vendored copy byte-identical to the merged substrate branch, prefault included), PHP 8.4:

suite      OK (108 tests, 108 assertions)
phpstan    level max, no errors
cs:check   clean

soak-arena-watermark:
  result slots: 320 spawns over a table of 64 — 1 records ever created, 319 recycled, 0 still out
  slots      plateau — flat at 1 slot record(s)     watermark  plateau +0.0 KiB
  allocated  plateau +0.0 KiB                        rss        plateau +0.0 KiB    PASS
soak-memory-flatness       PASS
soak-no-leftover-children  PASS
soak-preemption            PASS (2996 preemptions / 30.4 s, 0 wrong results, 2075/2075 fibers)
--self-test / --leak-slots both FAIL as required

Ad-hoc stress: 1600 concurrent-batch spawns over 24 slots (0 wrong, high-water 8, 0 outstanding); 240 spawns with 80 panics and repeat-awaits; 300 paced fire-and-forget spawns on a table that created one record; 50 unpaced spawns on a 4-slot table refused cleanly with the outstanding/retired counts named.

Known, pre-existing, not fixed here: sustained panics still exhaust the substrate's 256-entry registry (entries table full) — one persisted SharedError graph per panic. Reproduced identically on main; #19's ground, worth its own issue if panic-storm workloads matter.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U5QRWPfmkZME7hDjU6i5EA

---

Generated by Claude Code