feat(#253 PR3): optimistic-concurrency fan-out — Diff + Scalar aggregates #270

Merged
timothy merged 4 commits from feat/253-pr3-diff-scalar into main 2026-07-11 20:56:31 +02:00
Owner

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

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)
timothy added 1 commit 2026-07-11 19:24:47 +02:00
feat(253): PR3 optimistic-concurrency fan-out — Diff + Scalar aggregates
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 5s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m11s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 9m51s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
c40ffefa99
Fans the frozen Block recipe (api-conventions §7a) across the five Diff/Scalar
replace-all endpoints, completing the #253 PR2→PR4 arc's implementable core:

- #6 Collection custom-order, #7 Playout alternate-schedules, #8 Playout templates
  (shared Playout.Version), #9 MultiCollection, #10 RerunCollection — each: pre-check
  412 as a standalone Either after validation (H2, subtype survives the Join flatten),
  unconditional Version++ (M1), guarded save, controller If-Match/ETag/400/412, SPA
  editor ETag round-trip + 412 conflict dialog.
- H1: the two Playout handlers' catch(Exception)→422 restructured so the guard's
  PreconditionFailedError returns before the catch (412, not 422).
- M2: RerunCollection/Collection refresh runs unconditionally on save; MultiCollection
  keeps its name-only→no-rebuild optimization by bumping on the first (name) save.
- H3: UpdateDefaultDecoHandler bulk-bumps Playout.Version via .SetProperty.
- Shared ConcurrencyHeaders.MalformedIfMatchProblem() for the 400 guard.
- Deferred (→ #269): same-root non-bulk sibling config writers' ETag rotation.

Tests: per-handler pre-check/bump concurrency tests (Playout ×2 incl. non-vacuous
racing-save backstop, Rerun, Multi incl. name-only-no-rebuild M2, Collection);
controller tests get a DefaultHttpContext for the header read/write. Docs:
api-conventions §7a fan-out status, spa-conventions §4a list-editor note, decisions.

Refs #253

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
timothy added 1 commit 2026-07-11 19:37:00 +02:00
fix(253): force-write non-participating root writers past a concurrent Version bump (PR3 review)
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 7s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Failing after 2m33s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 3m30s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
e61f58cd99
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>
timothy added 1 commit 2026-07-11 19:45:09 +02:00
ci: retrigger — flake in unrelated LibrariesScreen scan-polling test (passes 13/13 locally)
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 5s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m59s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 10m38s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
f59f2362e2
timothy added 1 commit 2026-07-11 20:45:24 +02:00
Merge remote-tracking branch 'origin/main' into feat/253-pr3-diff-scalar
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 5s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m21s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 10m12s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Build ErsatzTV Image / Docs update reminder (push) Has been skipped
Build ErsatzTV Image / Build & push image (amd64) (push) Has been cancelled
Build ErsatzTV Image / Build & test (.NET) (push) Has been cancelled
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Has been cancelled
22440cc1e6
# Conflicts:
#	docs/decisions.md
timothy merged commit 22440cc1e6 into main 2026-07-11 20:56:31 +02:00
timothy deleted branch feat/253-pr3-diff-scalar 2026-07-11 20:56:31 +02:00
Sign in to join this conversation.