#259: content-aware stable child identity for schedule-item replace #276

Merged
timothy merged 5 commits from feat/259-child-identity into main 2026-07-11 22:11:28 +02:00
Owner

Closes #259.

PUT /api/schedules/{id}/items reconciled child rows by array position, so a moved/inserted schedule item inherited the fill-group/shuffle enumerator state (PlayoutScheduleItemFillGroupIndex, FK OnDelete(Cascade)) of whatever item previously occupied its new slot. This adds a stable child identity so state follows the logical item.

Contract (design signed off by Fable; api-conventions §7c + decisions.md)

  • ScheduleItemRequest.Id (int?) round-trips each existing item's server id (from the items GET). null / absent / 0 ⇒ new item (controller normalizes 0→null).
  • When any request item carries an id, the handler reconciles by id: matched same-subtype rows update in place (keep id → fill-group state follows the item across reorders/inserts); matched subtype-change → delete+insert (state resets, new id returned); unreferenced existing → delete; id-less → insert. Index stays array-position.
  • Fully id-less payload ⇒ verbatim positional fallback (legacy; retires with the §7a Phase-2 428 flip).
  • Guards run after §7a CheckVersion so 412 precedes 422: duplicate id → 422; id not in this schedule → 422 (a stale id under Phase-1 force-write is a live lost-update signal, not a new item). Both persist nothing.

Scope

Schedule items only — blocks/templates/deco-templates/playlists stay positional (stateless config children; nothing to misattribute). Deliberate asymmetry documented in §7c.

SPA

itemRules/SchedulesScreen round-trip the server id; new/copied drafts emit id: null (a copied row must not duplicate its source's id — pairs with the server duplicate-id guard). The PUT-response re-seed already existed and now carries ids through (a subtype switch changes the id server-side).

Tests

Reconcile matrix incl. the non-vacuous core (reorder moves state with the logical item — verified to fail under forced-positional), insert/delete, 422 guards, and 412-precedence. GET→map→PUT lossless round-trip now round-trips r.Id (exercises id-mode end-to-end). Backend 1410/1410, web lint/tsc/vitest green. OpenAPI + TS client regenerated.

🤖 Generated with Claude Code

Closes #259. `PUT /api/schedules/{id}/items` reconciled child rows by **array position**, so a moved/inserted schedule item inherited the fill-group/shuffle enumerator state (`PlayoutScheduleItemFillGroupIndex`, FK `OnDelete(Cascade)`) of whatever item previously occupied its new slot. This adds a stable child identity so state follows the **logical** item. ### Contract (design signed off by Fable; api-conventions §7c + decisions.md) - `ScheduleItemRequest.Id` (`int?`) round-trips each existing item's server id (from the items GET). **null / absent / 0 ⇒ new item** (controller normalizes `0`→null). - When any request item carries an id, the handler reconciles **by id**: matched same-subtype rows update in place (keep id → fill-group state follows the item across reorders/inserts); matched subtype-change → delete+insert (state resets, **new id returned**); unreferenced existing → delete; id-less → insert. `Index` stays array-position. - **Fully id-less payload ⇒ verbatim positional fallback** (legacy; retires with the §7a Phase-2 428 flip). - **Guards run after §7a `CheckVersion`** so **412 precedes 422**: duplicate id → 422; id not in this schedule → 422 (a stale id under Phase-1 force-write is a live lost-update signal, not a new item). Both persist nothing. ### Scope Schedule items **only** — blocks/templates/deco-templates/playlists stay positional (stateless config children; nothing to misattribute). Deliberate asymmetry documented in §7c. ### SPA `itemRules`/`SchedulesScreen` round-trip the server id; new/copied drafts emit `id: null` (a copied row must not duplicate its source's id — pairs with the server duplicate-id guard). The PUT-response re-seed already existed and now carries ids through (a subtype switch changes the id server-side). ### Tests Reconcile matrix incl. the non-vacuous core (reorder moves state with the logical item — **verified to fail under forced-positional**), insert/delete, 422 guards, and 412-precedence. GET→map→PUT lossless round-trip now round-trips `r.Id` (exercises id-mode end-to-end). Backend 1410/1410, web lint/tsc/vitest green. OpenAPI + TS client regenerated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
timothy added 4 commits 2026-07-11 21:55:21 +02:00
Add optional `int? Id` to ScheduleItemRequest/ReplaceProgramScheduleItem so
a client can round-trip each existing item's server id. When ids are present,
ReplaceProgramScheduleItemsHandler reconciles by id (not array position), so an
item's persisted fill-group/shuffle state (PlayoutScheduleItemFillGroupIndex,
FK OnDelete Cascade) follows the logical item across reorders/inserts instead of
being inherited by whatever previously occupied its new slot (#259, split from
#252/#253). A fully id-less payload keeps the verbatim positional fallback.

Guards (inside PersistItems, after CheckVersion so 412 precedes 422): duplicate
id -> 422; id not in this schedule -> 422 (a stale id under Phase-1 force-write is
a live lost-update signal, not a new item). Index stays array-position derived.

Regenerated v1.json + TS client.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The backend (already on this branch) added an optional int? Id to
ScheduleItemRequest so the server reconciles PUT /api/schedules/{id}/items
rows by identity instead of by array position. The SPA previously
discarded the server id on load (only a client-local _key survived) and
never sent one back, so a reorder could misattribute fill-group/shuffle
state onto the wrong persisted row.

- itemRules.ts: fromResponse now captures the response item's id onto
  the draft; normalizeForSave emits it back unchanged. newDraftItem and
  copyDraftItem explicitly set id: null (a brand-new/copied row was
  never persisted under an id, and copyDraftItem must not duplicate the
  source's id onto a second row).
- scheduleItem.ts (Add-to-schedule dialog, POST path): id: null for the
  same reason — it always creates a new row.
- SchedulesScreen.tsx save(): the PUT-response re-seed already existed
  (fromResponse over the response array) but now carries ids through.
  This matters because a subtype/playout-mode switch can be a
  delete+insert server-side, so the response id for that row can differ
  from what was submitted — a second save must use the *response's* id
  or the server 422s it as unknown. Added a comment documenting this.
- schedules.ts: replaced the stale "server reuses same-typed rows by
  position" comment with the current id-based reconcile contract.
- Added/updated tests in itemRules.test.ts, SchedulesScreen.test.tsx,
  and AddToScheduleDialog.test.tsx covering id round-tripping, the
  null-id-for-new/copied-item cases, and a second-save-reuses-the-
  response-id regression test.

Verified: npm run lint, tsc -b --noEmit, npm run build, and npm test
(680/680) all pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the id-based reconcile tests to ReplaceProgramScheduleItemsReconcileTests:
reorder moves state with the logical item (the non-vacuous core — proven to fail
under forced-positional), insert-in-middle, delete-unreferenced, unknown-id→422,
duplicate-id→422, and stale-version+unknown-id→412 (412 precedes 422, §7c). The
GET→map→PUT lossless round-trip now round-trips r.Id so it exercises id-mode.
Threads the new int? Id through all command/wire construction sites in tests.

Docs: api-conventions §7c (stable child identity + the deliberate #2-#5 positional
asymmetry) and a decisions.md entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
merge(#259): SPA round-trips schedule item server id
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 6s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 5m44s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m5s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
1864e4e15f
timothy added 1 commit 2026-07-11 22:03:35 +02:00
test(#259): cover id-mode subtype-change (delete+insert) with a same-type sibling
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 7s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m52s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 7m2s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
9e48aaefea
Review-caught coverage gap: the existing Subtype_Change test runs the POSITIONAL
path (id-less payload). Add a handler-level test for the id-mode branch — one
id-matched item changes subtype (One->Duration: delete+insert, new id) while a
sibling id-matched item keeps its subtype (Multiple: in place, id + fill-group
state preserved) in the same payload. Proves the delete pass + match-pass Remove/Add
don't double-handle and the survivor's state is retained.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
timothy merged commit 5e5a59317a into main 2026-07-11 22:11:28 +02:00
timothy deleted branch feat/259-child-identity 2026-07-11 22:11:28 +02:00
Sign in to join this conversation.