Concurrency Invariants
Name the guarantee before choosing a mutex, retry, transaction, lease, or idempotency key. Match the repo's architecture; do not force a framework or clarity-first redesign.
Choose scope
- Review: findings only. Give a possible interleaving and observable impact, not
there may be a race.
- Fix / design: enforce every live part of the contract below. Preserve APIs and local shape unless the guarantee requires a new seam; disclose it.
Build the contract before editing
Answer only what is live, but inspect every line:
- Guarantee: What must be impossible or remain true?
- Ownership: Which component owns each state and effect? Is coordination process-local, shared, or remote?
- Commit points: What changes atomically? Which effects cannot share that boundary?
- Replay: What can run again? What stable identity follows one logical operation to the owner that deduplicates it?
- Scheduling: What may overlap or reorder? What needs per-key serialization or fencing?
- Interruption: At each timeout, cancellation, or failure boundary, what may already have happened? What is pending, and who resumes or compensates?
A timeout or lost response is an unknown outcome unless the API proves the effect was not applied. Name only guarantees the mechanisms really provide.
Enforce every boundary
- Inside one owned store, use its transaction, compare-and-set, or uniqueness primitive when needed.
- A process-local lock protects one process. Shared leases need owner tokens or fencing so stale owners cannot commit after takeover.
- A local lock or transaction does not own a remote effect. Give replayable effects stable identity at the owner and reconcile unknown outcomes with that same identity.
- If one effect commits before another can happen, persist the pending work or compensation with the commit. Expose partial success instead of reporting that nothing happened.
- Retry only replay-safe, classified transient failures. Propagate cancellation to owned work; releasing local ownership does not determine a remote outcome.
One mechanism cannot satisfy guarantees across different owners. Do not stop after fixing the first race.
Completion gate
Before shipping, challenge the result with duplicate delivery, concurrent attempts, allowed reordering, timeout/cancellation around every commit point, failure between effects, and stale-owner completion. If a requested guarantee still depends on timing luck or an undocumented recovery path, the fix is incomplete.
Use deterministic barriers, controlled futures, or fake clocks, not real sleeps. Assert visible state and effect counts. Ship the fix or findings, focused checks, and any guarantee the existing seam cannot provide - no checklist dump.
1---2name: concurrency-invariants3description: Design, fix, or review concurrent and asynchronous code so atomicity, ordering, retries, idempotency, cancellation, timeouts, ownership, and partial success are explicit. Use for queues, workers, transactions, event handlers, parallel tasks, scheduled jobs, WebSocket/SSE, repeated delivery, concurrent requests, and race-condition fixes.4---56# Concurrency Invariants78Name the guarantee before choosing a mutex, retry, transaction, lease, or idempotency key. Match the repo's architecture; do not force a framework or clarity-first redesign.910## Choose scope1112- **Review:** findings only. Give a possible interleaving and observable impact, not `there may be a race`.13- **Fix / design:** enforce every live part of the contract below. Preserve APIs and local shape unless the guarantee requires a new seam; disclose it.1415## Build the contract before editing1617Answer only what is live, but inspect every line:18191. **Guarantee:** What must be impossible or remain true?202. **Ownership:** Which component owns each state and effect? Is coordination process-local, shared, or remote?213. **Commit points:** What changes atomically? Which effects cannot share that boundary?224. **Replay:** What can run again? What stable identity follows one logical operation to the owner that deduplicates it?235. **Scheduling:** What may overlap or reorder? What needs per-key serialization or fencing?246. **Interruption:** At each timeout, cancellation, or failure boundary, what may already have happened? What is pending, and who resumes or compensates?2526A timeout or lost response is an unknown outcome unless the API proves the effect was not applied. Name only guarantees the mechanisms really provide.2728## Enforce every boundary2930- Inside one owned store, use its transaction, compare-and-set, or uniqueness primitive when needed.31- A process-local lock protects one process. Shared leases need owner tokens or fencing so stale owners cannot commit after takeover.32- A local lock or transaction does not own a remote effect. Give replayable effects stable identity at the owner and reconcile unknown outcomes with that same identity.33- If one effect commits before another can happen, persist the pending work or compensation with the commit. Expose partial success instead of reporting that nothing happened.34- Retry only replay-safe, classified transient failures. Propagate cancellation to owned work; releasing local ownership does not determine a remote outcome.3536One mechanism cannot satisfy guarantees across different owners. Do not stop after fixing the first race.3738## Completion gate3940Before shipping, challenge the result with duplicate delivery, concurrent attempts, allowed reordering, timeout/cancellation around every commit point, failure between effects, and stale-owner completion. If a requested guarantee still depends on timing luck or an undocumented recovery path, the fix is incomplete.4142Use deterministic barriers, controlled futures, or fake clocks, not real sleeps. Assert visible state and effect counts. Ship the fix or findings, focused checks, and any guarantee the existing seam cannot provide - no checklist dump.
yakoshiq