hakorune/docs/reference/concurrency/semantics.md

## Concurrency Semantics (docs-only; to guide MVP)

Status: reference for userland Phase‑0. No runtime changes during the feature‑pause.

### Blocking & Non-Blocking
- `send(v)` blocks when the buffer is full (capacity reached). Unblocks when a receiver takes an item.
- `receive()` blocks when buffer is empty. Unblocks when a sender provides an item.
- `try_send(v) -> Bool`: returns immediately; false if full or closed.
- `try_receive() -> (Bool, Any?)`: returns immediately; false if empty and not closed.
- `receive_timeout(ms) -> (Bool, Any?)`: returns false on timeout.

Implementation note (Phase‑0): no busy loop. Use cooperative queues; later replaced by OS-efficient wait.

### Close Semantics
- `close()` marks the channel closed. Further `send` is an error.
- After close, `receive` continues to drain buffered items; once empty, returns a closed indicator (shape per API, e.g., `(false, End)`).
- Double close is an error.

### Select Semantics
- `when(channel, handler)` registers selectable cases.
- `await()` examines cases:
  - If one or more ready: choose one (random/round‑robin) and execute its handler atomically.
  - If none ready: Phase‑0 may block via a multi-wait helper or return false if non-blocking policy requested.
- Fairness: no starvation requirement; Phase‑0 uses simple fairness; Phase‑2 integrates runtime help.

### Structured Concurrency
- `RoutineScopeBox` owns spawned routines.
- On `fini()`: cancel pending children, bounded join, and ensure resource release.
- Cancellation should unblock channel waits promptly.

### Types & Safety
- Phase‑0: runtime tag checks on `ChannelBox` send/receive are optional; document expected element type.
- Future: `TypedChannelBox<T>` with static verification; falls back to runtime tags when needed.

### Observability
- Enable `NYASH_CONC_TRACE=1` to emit JSONL events.
- Event schema (recommendation):
  - Common: `ts` (ms), `op` (string), `rid` (routine id), `cid` (channel id, optional), `ok` (bool), `scope` (scope id, optional)
  - spawn/start/join/cancel: `{op:"spawn", rid, ts}`, `{op:"join", rid, ok, ts}`
  - send/recv: `{op:"send", cid, size, cap, ts}`, `{op:"recv", cid, size, cap, ts}`
  - park/unpark: `{op:"park", rid, reason, ts}`, `{op:"unpark", rid, reason, ts}`
  - select: `{op:"select", cases:n, chosen:k, ts}`
  - close: `{op:"close", cid, ts}`
- Causality: producers must emit before consumers observe; timestamps monotonic per process.

### Test Plan (smokes)
- ping_pong.hako: two routines exchange N messages; assert order and count.
- bounded_pc.hako: producer/consumer with capacity=1..N; ensure no busy-wait and correct totals.
- select_two.hako: two channels; verify first-ready choice and distribution.
- close_semantics.hako: send after close -> error; drain -> End; double close -> error.
- scope_cancel.hako: RoutineScopeBox cancels children; parked receivers unblocked.

### Migration Path
- Phase‑0 userland boxes are kept while Phase‑2 runtime grows; API stable.
- Replace cooperative wait with WaiterBox (Phase‑1) and runtime park/unpark later.