---
key: concurrency.idempotent-concurrent-add
title: '2026-07-18 — Concurrent same-item add is idempotent, not a 500: catch the unique-violation per provider (#308)'
status: active
since: '2026-07-18'
supersedes: none
superseded-by: none
rule: A concurrent duplicate `Add*ToCollection` that loses the race on the composite-key unique constraint is treated as an idempotent no-op (skip the reindex/rebuild fan-out), not a 500 — detected via a provider-specific `TvContext.IsUniqueConstraintViolation` delegate defaulting to "no".
signals: 'idempotent add, unique-constraint violation, provider error classifier · paths: `TvContext.IsUniqueConstraintViolation`, `SqliteErrorClassifier`, `MySqlErrorClassifier` · issues: #308, #269, #253'
mechanics: '`docs/api-conventions.md` §7a ("Idempotent insert under concurrency"); `ConcurrencyExtensions.TrySaveChangesForcingVersion`'
---

**Decision.** The `Add*ToCollection` family's membership pre-check (#269) is not atomic with the insert, so two
*concurrent* adds of the same item both observe it absent and both stage the `CollectionItem` composite key; the
loser's `SaveChangesForcingVersion` threw a unique/PK-violation `DbUpdateException` (SQLite error 19 / MySQL 1062)
it did not catch → **500**. We now treat that loss as an **idempotent no-op**, not an error: the desired end state
(the item is a member) already holds because the racing winner inserted it, rotated the ETag, and fanned out the
rebuild.

**Mechanism.** A `bool`-returning sibling `ConcurrencyExtensions.TrySaveChangesForcingVersion` wraps
`SaveChangesForcingVersion` and catches *only* a classified unique/PK violation, returning `false`. The 10
single-item handlers return `Unit.Default` on `false` (skip the reindex/rebuild fan-out — the winner did it). The
bulk `AddItemsToCollection` handler cannot no-op — that would silently drop the non-colliding items when a batch
partially overlaps a concurrent add — so it **retries** on a fresh context against recomputed membership (bounded
loop; the common no-collision path runs once).

**Provider seam.** Detection is provider-specific but the Application layer must not reference the provider
packages, so it follows the existing `TvContext` static-provider-config idiom (`IsSqlite`, `LastInsertedRowId`): a
settable `TvContext.IsUniqueConstraintViolation` delegate, pointed at `SqliteErrorClassifier` (extended codes 1555
PK / 2067 UNIQUE) or `MySqlErrorClassifier` (`Number == 1062`) from `Startup.cs`, defaulting to a conservative
"no" so an unwired provider never silently swallows a save failure. Chosen over DI to avoid threading a new
service through 11 handlers, and because the provider discriminator already lives as a `TvContext` static.

**Scope boundary.** `Add*ToPlaylist` is deliberately **untouched**: `PlaylistItem` has its own identity PK and no
unique index on `(PlaylistId, MediaItemId)` — a playlist may legitimately contain the same item more than once, so
there is no constraint to violate.

**Tests.** A negative-control anchor proves the race genuinely throws a classified `DbUpdateException`; the fix's
end-to-end handler tests reproduce a *real cross-connection* race via a shared-cache SQLite harness + a
`SavingChanges` interceptor that inserts the conflicting row on another connection mid-save (the single-connection
in-memory fixture cannot). Every fix-dependent test was verified to fail with the catch disabled. Mechanics:
`api-conventions.md` §7a ("Idempotent insert under concurrency"). Refs #308 #269 #253.
