writeonce/docs/stories/language-runtime-database/31-actor-lifecycle.md

iteration	status	chain
31	done	3

Iteration 31 — actor lifecycle: request/response, backpressure, death, timers

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Inserted 2026-08-21 (concurrency-chain re-sequence; the iteration was named as "new 31" in the 2026-08-20 code-review re-sequence — this is its story file). Third in the chain, stage 3 → 22 → 31 → 24 → 23 → 32: chat (iteration 24) cannot be written honestly without these four mechanisms.

✅ LANDED 2026-08-27 — INSIDE 24, per the 2026-08-23 directive that absorbed it. All four mechanisms shipped: call/reply with a typed scalar reply (id 88, WO-E226), bounded mailboxes (WO_MAILBOX, default 1024, fail-fast with a catchable WO_T_ACTOR), actor death that traps callers instead of hanging them, monitor (id 89) and time.after (id 90). Ids 89 and 90 were reserved holes in wob.h; they are filled.

A fifth mechanism was added that this story did not anticipate: the shutdown drain guarantee, 40. It is lifecycle semantics — this story gave actors a death notice, 40 gives the program a shutdown that does not lose mail — and it was found by measurement while proving 24's gate, not by review.

How each piece works: runtime/src/CODE-LOGIC.md, "Actor lifecycle".

Why this iteration exists

The arc's stages 1+2 shipped spawn/send mechanism without lifecycle: send is one-way and callers sleep-poll to await an answer; the mailbox FIFO grows without bound (a hot sender can exhaust a shard's memory); an actor that traps dies silently (nobody learns, nothing restarts, its mailbox rots); and there is no timer surface beyond a fiber blocking in time.sleep. Every real serving program — chat first — is made of request/response turns, bounded queues, death notices, and deadlines. Without this iteration the arc is a demo, not a runtime.

Goals

• Request/response over one-way sends. A caller can send and park until the reply arrives — one surface, no sleep-polling, no second concurrency vocabulary. Ownership rules unchanged: the request moves, the reply moves back.
• Bounded mailboxes with a stated backpressure policy. A mailbox has a cap; what happens at the cap (park the sender vs error) is decided by the spec, one policy, doctrine-pure — no silent unbounded growth anywhere in the runtime.
• Actor death is observable. A trap or normal exit produces a signal another actor can receive; a fiber-trap already isolates (stage 1) — this makes the fact of death deliverable, so a supervisor CAN be written in .wo.
• Timers as messages. A deadline or interval delivers to a mailbox like any other send, riding the shard's existing io_uring/epoll timeout plumbing (arc T4) — no new event loop.

Acceptance Criteria (draft — the spec refines)

• What to achieve?
  • Given an actor that answers requests,
  • when a caller awaits the reply,
  • then the caller's fiber parks (the shard serves other fibers, TID-verified), resumes with the moved reply, and never busy-waits.
• What to achieve?
  • Given a mailbox at its cap,
  • when another send arrives,
  • then the stated backpressure policy fires deterministically, memory stays bounded (RSS flat under a hot-sender soak), and no message is silently dropped.
• What to achieve?
  • Given an actor that traps mid-message,
  • when it dies,
  • then its drop maps run (ASan zero leaks), a death signal reaches the observer that asked for one, and a supervisor written in .wo can respawn it.
• What to achieve?
  • Given a timer armed by an actor,
  • when it fires,
  • then the actor receives it as an ordinary message on its own shard, and cancelling before expiry means it never delivers.

Out Of Scope

• Supervision TREES / OTP-scale restart policy — a .wo library once death signals exist, not runtime policy.
• Priorities and custom scheduling — the reduction budget stays the only fairness mechanism.
• Distributed (cross-process) supervision — no network layer exists.
• Changing the ownership-move rule or the unified address surface — iteration 8's decisions stand.

Info

Forks the spec must settle:

1. The request/response surface. A reply-address baked into the message shape vs a runtime-level call that parks — and what the compiler checks (does a request type name its reply type?).
2. The backpressure policy at the cap. Park the sender (natural with fibers, risks deadlock cycles) vs fail the send (explicit, pushes handling to the program). One policy, stated; not configurable per mailbox in v1.
3. The death-signal shape. Erlang's link (bidirectional, dies together) vs monitor (one-way notice) — likely monitor-only v1.
4. The timer surface. Builtin (time.after delivering a message) vs actor-spawned sleeper fiber — and cancellation semantics.

Sources: the 2026-08-20 code-review findings (the gaps this iteration answers), the arc plan's stage-2 deviations (2026-08-20-shard-fiber-arc.md — the unbounded FIFO is deviation 4's mutex inbox), and BEAM precedent already surveyed in docs/plan/exploration/fibers/00-fibers.md.

Proposed Solution

Brainstorm → spec → plan after the arc's stage 3 lands and iteration 22 has its baseline (the mailbox-cap and inbox-ring decisions want 22's mutex number). The spec is written against iteration 24's needs — chat names the lifecycle mechanisms it consumes, this iteration names chat as its first honest consumer.