---
name: concurrency-reasoning
description: Async/concurrent/streaming discipline — five questions (overlapping runs, check-then-act, mutation across await, response ordering, cancellation), idempotent retries, shared-state audit, race amplification. Use for async fan-out, streams/SSE, jobs, caches, or flaky timing-smell bugs.
---

# Concurrency Reasoning

Concurrency bugs don't announce themselves in review — the code reads fine sequentially. The discipline is asking a fixed set of questions about every async surface, because the compiler won't.

## The core question set (ask for every async/shared surface)

1. **What happens if this runs twice, overlapping?** Two clicks, two requests, a retry racing the original, cron overlapping its previous run. If the answer involves corrupted state or double effects, you need a guard (idempotency key, mutex, request de-dupe, disable-on-click).
2. **What happens between the check and the act?** Every `if (exists) then update` on shared state is a TOCTOU window. Close it with atomic operations (upsert, compare-and-swap, unique constraints, transactions) — not with a smaller window.
3. **Who else mutates this while I await?** Every `await` is a yield point: module-level variables, caches, and objects captured by closures can change under you mid-function. Re-read state after awaits if it matters; don't cache pre-await reads across the gap.
4. **What order do these land in?** Two in-flight requests resolve in either order. If responses update the same state (search-as-you-type, autosave), guard with sequence numbers / "latest wins" checks / cancellation of the superseded one.
5. **What happens on cancellation/unmount/disconnect mid-flight?** Streaming handlers and UI callbacks firing after teardown → guard with abort signals, mounted flags, or subscription cleanup. Partial effects from an aborted multi-step operation need cleanup or resumability.

## Retries and exactly-once

- **Retry only idempotent operations** — or make them idempotent first (idempotency keys, natural unique constraints). A retried "create" without one is a duplicate.
- Retries need backoff + jitter + a cap; retrying immediately in a loop is a DoS on your own dependency.
- Distinguish "the request failed" from "the request's *response* failed" — the operation may have succeeded server-side. Design reads-back or upserts accordingly.

## Shared-state audit (for the diff you're writing)

Enumerate every piece of state your async code touches that outlives one invocation: module globals, singletons, caches, class fields, DB rows, files. For each: who writes it, from how many concurrent contexts, and what serializes those writes? "Nothing serializes them, but it's probably fine" is a bug report from the future.

## Debugging suspected races

- Flaky test / intermittent failure → don't rerun until green. Amplify instead: run 20–100× in a loop, add load, add artificial delays (`sleep` at suspected interleaving points) to widen the window and make it deterministic.
- Bisect by interleaving, not by code: log timestamps + IDs at each async boundary and reconstruct the actual order of the failing run.
- The fix must name the interleaving it prevents. "Added a lock and it stopped failing" without knowing the race is a hidden deadlock waiting.

## Deadlock/starvation reflexes

Consistent lock ordering; never hold a lock across an await/IO; timeouts on anything that waits on another party; bounded queues (an unbounded queue turns backpressure into an OOM).