# 1. Repair decision **Decision: OPTIMISTIC-CONCURRENCY CONTRACT DRIFT FOUND — SAFE LOCAL PATCH AVAILABLE; production records and queued mutations remain unverified.** # 2. Scope and boundary **Reviewed:** schemas, Prisma models, repositories, routes, services, BullMQ workers, Redis handlers, events, tests, fixtures, docs, and runbook. **Not accessed:** production PostgreSQL, Redis, BullMQ, customer records, deployed workers, or migrations. # 3. Concurrency contract source register | Source | Current behavior | Status | |---|---|---| | Prisma models | integer `version` on some entities | Candidate | | profile route | checks version | Partial | | settings route | ignores version | Lost-update risk | | preference mutation | trusts client timestamp | Invalid token | | worker payload | entity ID only | Stale-job risk | | Redis cache | no version metadata | Projection drift | | admin edit | direct `updateMany` | Bypass | | API errors | mixed 200/400/409 | Response drift | | tests | sequential only | Coverage gap | # 4. Canonical repository contract Automatic merge behavior, bulk conflict policy, and legacy-job treatment are **OWNER DECISION REQUIRED**. Safe contract: - protected aggregates expose one opaque version token; - callers submit the token they read; - repositories perform one atomic compare-and-set; - successful writes increment the version once; - zero matched rows become a typed conflict; - workers carry expected version and stable command ID; - retries never turn stale commands into unconditional writes; - cache and event consumers reject older versions. # 5. Drift findings ## F1 — Partial enforcement Only one route checks `version`. **Repair:** route protected mutations through one command requiring `expectedVersion`. ## F2 — Timestamp token A device timestamp is not a reliable lock token. **Repair:** use the server-controlled integer version. Keep timestamps for display and audit only. ## F3 — Read-compare-write gap One service compares in application code, then issues an unconditional update. **Repair:** condition the database update on entity ID, tenant, and expected version while incrementing the version in the same operation. Zero rows means conflict. ## F4 — Stale worker overwrite A delayed job can apply an older command after a newer API change. **Repair:** include command ID, expected version, and requested patch. On conflict, record a bounded terminal or review-required result. Do not reload and overwrite automatically. ## F5 — Cache and event drift Redis and lifecycle events omit source versions. **Repair:** include version metadata and ignore older projection updates. ## F6 — Bulk bypass `updateMany` changes protected fields without per-record conditions. **Repair:** require per-record tokens for normal admin edits and return individual success or conflict results. Keep any maintenance bypass explicit and owner-approved. ## F7 — Response drift Stale writes return inconsistent status codes. **Repair:** map a typed `ConcurrencyConflict` to the approved 409 response. Keep validation, authorization, not-found, and conflict separate. # 6. Safe patch plan | Area | Change | |---|---| | Domain | opaque version token and typed conflict | | API | required expected-version input | | Repository | atomic compare-and-set | | Workers | stable command ID and version | | Bulk tools | per-record outcomes | | Cache/events | monotonic version handling | | Tests/docs | writers, stale jobs, and responses | # 7. Deterministic test matrix 1. Current-version write succeeds and increments once. 2. A second writer using the old version conflicts. 3. Two concurrent updates produce one winner. 4. Zero matched rows cannot return success. 5. Tenant and authorization filters remain in the conditional write. 6. Client timestamps cannot substitute for versions. 7. A delayed worker cannot overwrite newer state. 8. Worker retry reuses command ID and expected version. 9. Older cache or event projections are ignored. 10. Bulk edits report per-record outcomes. 11. Validation, not-found, forbidden, and conflict remain distinct. 12. Tests use local services only. # 8. Verification steps Run: - `npm test -- optimistic-lock` - `npm test -- concurrent-mutations` - `npm test -- worker-version-conflicts` - `npm test -- versioned-cache` - `npm test -- bulk-edit-conflicts` - `npm run typecheck` - `npm run lint` - `npm run build` Search for unconditional updates, `updatedAt` used as a token, reload-and-retry conflict handlers, jobs without command identity, and cache writes without versions. # 9. Production boundary Unknown: inconsistent existing versions, old clients without tokens, queued legacy jobs, external scripts, stale Redis values, mixed worker versions, and rollout requirements. # 10. Human approval request **Safe now:** shared version types, compare-and-set writes, typed 409 conflicts, versioned worker commands, monotonic projections, per-record bulk outcomes, tests, and docs. **Decisions required:** merge policy, conflict payload, maintenance bypasses, legacy clients, old jobs, backfill, and rollout order. **Status: PATCH READY FOR LOCAL REVIEW — MERGE POLICY, PRODUCTION VERSIONS, LEGACY CLIENTS, QUEUED COMMANDS, AND DEPLOYED BEHAVIOR NOT VERIFIED** # 11. Suggested commit message `fix(concurrency): enforce versioned writes across API and workers`