PR3 of the #253 optimistic-concurrency arc. Fans the frozen Block recipe (api-conventions.md §7a) across the five Diff/Scalar replace-all endpoints — the implementable core of the PR2→PR4 arc. Parallel-safe with PR2 (RR + Reconcile); disjoint handler surfaces, no migration (Version columns shipped in PR1).
Endpoints wired (full contract each)
#
Endpoint
Mechanism
Notes
6
PUT /api/collections/{id}/custom-order
in-place
204 carries new ETag; M2 refresh unconditional
7
PUT /api/playouts/{id}/alternate-schedules
Diff
H1 catch-restructure; shares Playout.Version
8
PUT /api/playouts/{id}/templates
Diff
H1; no root scalar → bump is the only root write
9
PUT /api/multi-collections/{id}
Diff
M2 name-only→no-rebuild preserved (bump on first save)
10
PUT /api/rerun-collections/{id}
Scalar
M2 refresh unconditional
Each: pre-check 412 as a standalone Either after validation (H2 — subtype survives the Join() flatten, proven by the pre-check tests), unconditional Version++ (M1), SaveChangesWithConcurrencyGuard, controller If-Match parse (400 on malformed) + ETag on GET + new ETag on success + [ProducesResponseType] 400/412, and the SPA editor ETag round-trip + 412 conflict dialog.
Judgment calls (design §9)
H1 — the two Playout handlers wrap SaveChangesAsync in a catch(Exception)→422. The guard returns a PreconditionFailedErrorLeft as a value and the handler returns it before the post-commit block, so it never reaches the catch → 412 not 422.
M2 — SaveChangesAsync() > 0 gates flip always-true under the unconditional bump. Rerun/Collection run the refresh unconditionally; MultiCollection bumps on its first (name) save so the second (items) save's > 0 still means "items changed" → a name-only edit bumps + rotates the ETag but doesn't rebuild playouts.
H3 — UpdateDefaultDecoHandler bulk-bumps Playout.Version via .SetProperty (bulk ExecuteUpdate can't throw the concurrency exception).
Deferred → #269 — other same-root non-bulk config writers don't yet rotate the ETag; adding an unconditional bump to a plain-SaveChangesAsync handler would open a new 500 path, so it needs a uniform guard+bump+412 pass (fold into #197). The primary endpoints' own bump+guard fully cover the two-tab lost-update the issue targets.
Tests
Per-handler pre-check/matching/force-write + bump concurrency tests: Playout ×2 (incl. a non-vacuous racing-save backstop — verified it fails with IsConcurrencyToken dropped), Rerun, MultiCollection (incl. name-only→no-rebuild M2), Collection custom-order. Existing controller tests gained a DefaultHttpContext so the header read/write works in unit tests. Full suites green: ErsatzTV.Tests 1310, Core.Tests 493, web 663; check:api/typecheck/lint clean.
PR3 of the #253 optimistic-concurrency arc. Fans the frozen Block recipe (`api-conventions.md` §7a) across the five Diff/Scalar replace-all endpoints — the implementable core of the PR2→PR4 arc. Parallel-safe with PR2 (RR + Reconcile); disjoint handler surfaces, no migration (Version columns shipped in PR1).
## Endpoints wired (full contract each)
| # | Endpoint | Mechanism | Notes |
|---|---|---|---|
| 6 | `PUT /api/collections/{id}/custom-order` | in-place | 204 carries new ETag; M2 refresh unconditional |
| 7 | `PUT /api/playouts/{id}/alternate-schedules` | Diff | **H1** catch-restructure; shares `Playout.Version` |
| 8 | `PUT /api/playouts/{id}/templates` | Diff | **H1**; no root scalar → bump is the only root write |
| 9 | `PUT /api/multi-collections/{id}` | Diff | **M2** name-only→no-rebuild preserved (bump on first save) |
| 10 | `PUT /api/rerun-collections/{id}` | Scalar | **M2** refresh unconditional |
Each: pre-check 412 as a **standalone `Either` after validation** (H2 — subtype survives the `Join()` flatten, proven by the pre-check tests), unconditional `Version++` (M1), `SaveChangesWithConcurrencyGuard`, controller `If-Match` parse (400 on malformed) + ETag on GET + new ETag on success + `[ProducesResponseType] 400/412`, and the SPA editor ETag round-trip + 412 conflict dialog.
## Judgment calls (design §9)
- **H1** — the two Playout handlers wrap `SaveChangesAsync` in a `catch(Exception)`→422. The guard returns a `PreconditionFailedError` **Left as a value** and the handler returns it before the post-commit block, so it never reaches the catch → 412 not 422.
- **M2** — `SaveChangesAsync() > 0` gates flip always-true under the unconditional bump. Rerun/Collection run the refresh unconditionally; MultiCollection bumps on its **first** (name) save so the **second** (items) save's `> 0` still means "items changed" → a name-only edit bumps + rotates the ETag but doesn't rebuild playouts.
- **H3** — `UpdateDefaultDecoHandler` bulk-bumps `Playout.Version` via `.SetProperty` (bulk `ExecuteUpdate` can't throw the concurrency exception).
- **Deferred → #269** — other same-root non-bulk config writers don't yet rotate the ETag; adding an unconditional bump to a plain-`SaveChangesAsync` handler would open a new 500 path, so it needs a uniform guard+bump+412 pass (fold into #197). The primary endpoints' own bump+guard fully cover the two-tab lost-update the issue targets.
## Tests
Per-handler pre-check/matching/force-write + bump concurrency tests: Playout ×2 (incl. a **non-vacuous** racing-save backstop — verified it fails with `IsConcurrencyToken` dropped), Rerun, MultiCollection (incl. name-only→no-rebuild M2), Collection custom-order. Existing controller tests gained a `DefaultHttpContext` so the header read/write works in unit tests. Full suites green: ErsatzTV.Tests 1310, Core.Tests 493, web 663; `check:api`/typecheck/lint clean.
## Docs
`api-conventions.md` §7a fan-out status + deferral; `spa-conventions.md` §4a list-editor by-id-for-token note; `decisions.md` (H1/M2/deferral/VMs); regenerated `v1.json`/`v1.d.ts`.
Refs #253 · follow-up #269
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Adversarial review caught a HIGH the fan-out introduced: activating Version as an
IsConcurrencyToken on Playout/Collection makes EF append `WHERE Version=@orig` to
EVERY root UPDATE, so a non-If-Match writer that saves via plain SaveChangesAsync
now throws DbUpdateConcurrencyException → 500 when a replace-all editor bumps the
row between its load and save. Realistic two-tab trigger (edit playout settings while
editing its alt-schedules; edit a collection's name while reordering) — a new crash,
previously silent last-write-wins.
Fix: shared ConcurrencyExtensions.SaveChangesForcingVersion — on a concurrency
failure it adopts the stored token as original+current (client-wins merge scoped to
the token, never reverting the concurrent bump) and retries, i.e. Phase-1 force-write
semantics for a missing If-Match. Applied to the exposed UPDATE writers:
UpdatePlayout, Update{Sequential,Scripted,ExternalJson}Playout, UpdateOnDemandCheckpoint,
UpdateCollection. Non-vacuous test proves the write lands and the bump survives.
Deletes + repo-mediated Add* writers (rarer / join-rows-only) re-scoped onto #269.
Refs #253#269
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
PR3 of the #253 optimistic-concurrency arc. Fans the frozen Block recipe (
api-conventions.md§7a) across the five Diff/Scalar replace-all endpoints — the implementable core of the PR2→PR4 arc. Parallel-safe with PR2 (RR + Reconcile); disjoint handler surfaces, no migration (Version columns shipped in PR1).Endpoints wired (full contract each)
PUT /api/collections/{id}/custom-orderPUT /api/playouts/{id}/alternate-schedulesPlayout.VersionPUT /api/playouts/{id}/templatesPUT /api/multi-collections/{id}PUT /api/rerun-collections/{id}Each: pre-check 412 as a standalone
Eitherafter validation (H2 — subtype survives theJoin()flatten, proven by the pre-check tests), unconditionalVersion++(M1),SaveChangesWithConcurrencyGuard, controllerIf-Matchparse (400 on malformed) + ETag on GET + new ETag on success +[ProducesResponseType] 400/412, and the SPA editor ETag round-trip + 412 conflict dialog.Judgment calls (design §9)
SaveChangesAsyncin acatch(Exception)→422. The guard returns aPreconditionFailedErrorLeft as a value and the handler returns it before the post-commit block, so it never reaches the catch → 412 not 422.SaveChangesAsync() > 0gates flip always-true under the unconditional bump. Rerun/Collection run the refresh unconditionally; MultiCollection bumps on its first (name) save so the second (items) save's> 0still means "items changed" → a name-only edit bumps + rotates the ETag but doesn't rebuild playouts.UpdateDefaultDecoHandlerbulk-bumpsPlayout.Versionvia.SetProperty(bulkExecuteUpdatecan't throw the concurrency exception).SaveChangesAsynchandler would open a new 500 path, so it needs a uniform guard+bump+412 pass (fold into #197). The primary endpoints' own bump+guard fully cover the two-tab lost-update the issue targets.Tests
Per-handler pre-check/matching/force-write + bump concurrency tests: Playout ×2 (incl. a non-vacuous racing-save backstop — verified it fails with
IsConcurrencyTokendropped), Rerun, MultiCollection (incl. name-only→no-rebuild M2), Collection custom-order. Existing controller tests gained aDefaultHttpContextso the header read/write works in unit tests. Full suites green: ErsatzTV.Tests 1310, Core.Tests 493, web 663;check:api/typecheck/lint clean.Docs
api-conventions.md§7a fan-out status + deferral;spa-conventions.md§4a list-editor by-id-for-token note;decisions.md(H1/M2/deferral/VMs); regeneratedv1.json/v1.d.ts.Refs #253 · follow-up #269
🤖 Generated with Claude Code
Adversarial review caught a HIGH the fan-out introduced: activating Version as an IsConcurrencyToken on Playout/Collection makes EF append `WHERE Version=@orig` to EVERY root UPDATE, so a non-If-Match writer that saves via plain SaveChangesAsync now throws DbUpdateConcurrencyException → 500 when a replace-all editor bumps the row between its load and save. Realistic two-tab trigger (edit playout settings while editing its alt-schedules; edit a collection's name while reordering) — a new crash, previously silent last-write-wins. Fix: shared ConcurrencyExtensions.SaveChangesForcingVersion — on a concurrency failure it adopts the stored token as original+current (client-wins merge scoped to the token, never reverting the concurrent bump) and retries, i.e. Phase-1 force-write semantics for a missing If-Match. Applied to the exposed UPDATE writers: UpdatePlayout, Update{Sequential,Scripted,ExternalJson}Playout, UpdateOnDemandCheckpoint, UpdateCollection. Non-vacuous test proves the write lands and the bump survives. Deletes + repo-mediated Add* writers (rarer / join-rows-only) re-scoped onto #269. Refs #253 #269 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>