ersatztv/docs/decisions/records/concurrency/force-write-non-ifmatch.md

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics

key	title	status	since	supersedes	superseded-by	rule	signals	mechanics
concurrency.force-write-non-ifmatch	2026-07-12 (#269 — non-If-Match root writers force-write past a concurrent Version bump)	active	2026-07-12	none	none	Any handler that leaves a versioned root `Modified` or `Deleted` but takes no `If-Match` (deletes, item add/remove bumpers, scalar-config writers) must save through `ConcurrencyExtensions.SaveChangesForcingVersion` — force-write past a concurrent `Version` bump rather than throw an unhandled `DbUpdateConcurrencyException` (500).	force-write, non-If-Match writers, DbUpdateConcurrencyException · paths: `ConcurrencyExtensions.SaveChangesForcingVersion` · issues: #269, #253, #302, #197	`RootWriterForceVersionTests`; `docs/api-conventions.md` §7a

Routing the aggregate delete handlers + UpdateProgramScheduleHandler through SaveChangesForcingVersion. Once #253 made each replace-all root's Version an IsConcurrencyToken, EF started guarding every UPDATE and DELETE of that row with WHERE Version=@orig — so any writer that is not part of the If-Match contract but still saves via plain SaveChangesAsync throws an unhandled DbUpdateConcurrencyException→500 if a replace-all editor bumps the row in its narrow load→save window. PR3 already force-wrote the exposed UPDATE siblings (Playout settings/ScheduleFile/checkpoint, UpdateCollectionHandler); a completeness sweep for #269 found the gap was wider than reported — 18 writers in total, all on plain SaveChangesAsync. The correct exposure filter is "any handler that leaves a versioned root Modified or Deleted", NOT just Version-bumpers + deletes — an early sweep used the narrower filter and a review of PR #302 caught what it missed (ErasePlayoutHistory below):

• the nine versioned-root delete handlers (DeletePlayout/DeleteCollection/DeleteMultiCollection/ DeleteRerunCollection/DeletePlaylist/DeleteBlock/DeleteTemplate/DeleteDecoTemplate/ DeleteProgramSchedule) — a DELETE is now token-guarded too;
• UpdateProgramScheduleHandler (bumps Version then saved plainly — the ProgramSchedule case PR3 only suspected);
• the seven item add/remove bumpers that PR2 wired to bump their root but left on plain save — AddProgramScheduleItem/DeleteProgramScheduleItem and the five Add{Items,Movie,Show,Season,Episode}ToPlaylist handlers;
• ErasePlayoutHistoryHandler — modifies Playout root scalars (Seed/Anchor/OnDemandCheckpoint) without bumping Version, inside an explicit transaction with no try/catch → the one the bumper-only filter missed; reachable via POST /api/playouts/{id}/erase-items-and-history.

All now save through ConcurrencyExtensions.SaveChangesForcingVersion.

Two deliberate boundaries (documented, not gaps): (1) the background build/time-shift Playout-scalar writers (BuildPlayoutHandler via PlayoutBuilder's Anchor/Seed; PlayoutTimeShifter's OnDemandCheckpoint) are token-guarded too but intentionally left on plain save — they never surface a request-path 500 (BuildPlayoutHandler catches → a build-failure BaseError; PlayoutTimeShifter runs only via the background worker), and force-writing would be wrong: a concurrent config edit that bumped Version also enqueues a rebuild, so failing the in-flight build and letting the rebuild redo it with fresh config is correct (force-writing would persist output built from stale config). (2) Item-add force-write can leave a duplicate/gap Index (accepted Phase-1 effect): the handler computes the new index from its stale child list, so if a concurrent replace-all grew the list the item lands at a now-colliding index (no unique constraint on PlaylistItem.Index/ProgramScheduleItem.Index) — non- corrupting, self-correcting on the next edit, still strictly better than the pre-#269 500; a reload-and-recompute-on-conflict refinement is a candidate for #197. Decision: force-write, not 412 — these endpoints take no If-Match (an unconditional DELETE/settings-edit should win over a concurrent editor), matching the Phase-1 force-write posture. A delete has no ETag to rotate, so it needs only the force-write, not a Version bump. A genuine row-deletion race (two concurrent deletes) still surfaces as a DbUpdateConcurrencyException — accepted (rare, non-corrupting, the resource is already gone). Still deferred to #197: cross-editor ETag rotation for the non-bumping config siblings and the scanner-shared Add*ToCollection family (they don't 500 — they insert children / ExecuteDelete, neither of which is token-guarded — they just don't rotate an open editor's ETag). Non-vacuously tested by racing a bump through the handler via a pre-tracked context (RootWriterForceVersionTests), plus an explicit negative control proving the plain-save path throws.