#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
21 changed files with 590 additions and 40 deletions
@@ -5,6 +5,7 @@ using ErsatzTV.Core.Scheduling;
namespace ErsatzTV.Application.ProgramSchedules;
public record ReplaceProgramScheduleItem(
int? Id,
int Index,
StartType StartType,
TimeSpan? StartTime,
@@ -48,16 +48,22 @@ public class ReplaceProgramScheduleItemsHandler(
ProgramSchedule programSchedule,
CancellationToken cancellationToken)
{
// Positional in-place reconcile (rather than delete-and-reinsert): a schedule item owns the
// persisted fill-group/shuffle enumerator state via PlayoutScheduleItemFillGroupIndex, whose
// In-place reconcile (rather than delete-and-reinsert): a schedule item owns persisted
// fill-group/shuffle enumerator state via PlayoutScheduleItemFillGroupIndex, whose
// ProgramScheduleItemId FK is OnDelete(Cascade). Removing and re-inserting every item — as the
// original handler did on every save, including a no-op PUT-back — cascade-deleted that state for
// all playouts using the schedule (#252). Reusing the existing item row for the same-typed slot
// keeps its id, so the cascade never fires and progression survives. The request DTO carries no
// stable item id, so position is the only key available here; true content-aware stable identity
// is deferred to the shared concurrency/round-trip contract in #253.
// all playouts using the schedule (#252). Reusing the existing item row keeps its id, so the cascade
// never fires and progression survives.
//
// Two reconcile modes (#259):
// * id-based (preferred) — when the client round-trips each existing item's server id, map request
// items to existing rows BY id, so per-child state follows the LOGICAL item across reorders and
// mid-list inserts rather than staying with whatever previously occupied a slot.
// * positional (legacy fallback) — a fully id-less payload keeps the original by-array-position
// reconcile. This preserves today's misattribution on legacy reorders; it is temporary and
// retires with the §7a Phase-2 If-Match flip.
// Index (ordering) is always derived from array position; identity (id) is a separate axis.
var orderedItems = request.Items.OrderBy(i => i.Index).ToList();
List<ProgramScheduleItem> existingItems = programSchedule.Items.OrderBy(i => i.Index).ToList();
// load the watermark/graphics join rows for the existing items so they can be rebuilt in place
await dbContext.Entry(programSchedule)
@@ -67,39 +73,112 @@ public class ReplaceProgramScheduleItemsHandler(
.Include(i => i.ProgramScheduleItemGraphicsElements)
.LoadAsync(cancellationToken);
int commonCount = Math.Min(existingItems.Count, orderedItems.Count);
for (var i = 0; i < commonCount; i++)
List<ProgramScheduleItem> existingItems = programSchedule.Items.ToList();
List<int> requestIds = orderedItems.Where(i => i.Id.HasValue).Select(i => i.Id.Value).ToList();
if (requestIds.Count == 0)
{
ProgramScheduleItem existing = existingItems[i];
ProgramScheduleItem built = BuildItem(programSchedule, i, orderedItems[i]);
if (existing.GetType() == built.GetType())
// ---- positional fallback (verbatim pre-#259 behavior) ----
List<ProgramScheduleItem> orderedExisting = existingItems.OrderBy(i => i.Index).ToList();
int commonCount = Math.Min(orderedExisting.Count, orderedItems.Count);
for (var i = 0; i < commonCount; i++)
{
// same TPT subtype: copy all scalar values in place (BuildItem is the single source of
// item construction, so no field is silently dropped) and rebuild the join rows, keeping
// the item's id — and with it the fill-group index that would otherwise cascade away.
built.Id = existing.Id;
dbContext.Entry(existing).CurrentValues.SetValues(built);
RebuildChildren(existing, orderedItems[i]);
ProgramScheduleItem existing = orderedExisting[i];
ProgramScheduleItem built = BuildItem(programSchedule, i, orderedItems[i]);
if (existing.GetType() == built.GetType())
{
built.Id = existing.Id;
dbContext.Entry(existing).CurrentValues.SetValues(built);
RebuildChildren(existing, orderedItems[i]);
}
else
{
dbContext.Remove(existing);
programSchedule.Items.Add(built);
}
}
else
for (int i = commonCount; i < orderedExisting.Count; i++)
{
// EF can't change a TPT row's type in place; this slot must be replaced (its fill-group
// index resets, which is acceptable — the item fundamentally changed).
dbContext.Remove(existing);
programSchedule.Items.Add(built);
dbContext.Remove(orderedExisting[i]);
}
for (int i = commonCount; i < orderedItems.Count; i++)
{
programSchedule.Items.Add(BuildItem(programSchedule, i, orderedItems[i]));
}
}
// remove surplus existing items
for (int i = commonCount; i < existingItems.Count; i++)
else
{
dbContext.Remove(existingItems[i]);
}
// ---- id-based reconcile ----
// Guards run HERE (inside PersistItems, after CheckVersion in Handle) so a client that is BOTH
// version-stale and id-stale gets 412 (reload signal) — not 422, which reads as a payload bug
// (§7c). Both guards persist nothing (plain BaseError → 422).
// add surplus incoming items
for (int i = commonCount; i < orderedItems.Count; i++)
{
programSchedule.Items.Add(BuildItem(programSchedule, i, orderedItems[i]));
// 7b: a duplicated id would map two request items onto one row (SetValues twice, last-writer-wins,
// one item's config silently lost). Always a client bug.
int? duplicateId = requestIds.GroupBy(id => id).Where(g => g.Count() > 1).Select(g => (int?)g.Key)
.FirstOrDefault();
if (duplicateId.HasValue)
{
return new BaseError($"Schedule item id {duplicateId.Value} appears more than once in the request.");
}
// 7a: an id not belonging to THIS schedule is a stale/foreign identity. Under Phase-1 (a missing
// If-Match force-writes) it is a live lost-update signal; inserting-as-new would silently duplicate
// the item and return a different id than the client sent. Reject loudly rather than mask it.
var existingIds = existingItems.Select(e => e.Id).ToHashSet();
foreach (int id in requestIds)
{
if (!existingIds.Contains(id))
{
return new BaseError($"Schedule item id {id} does not belong to this schedule.");
}
}
// delete pass: existing rows the request no longer references (their fill-group state cascades —
// correct, the logical item is gone)
var referencedIds = requestIds.ToHashSet();
foreach (ProgramScheduleItem existing in existingItems)
{
if (!referencedIds.Contains(existing.Id))
{
dbContext.Remove(existing);
}
}
// match/insert pass in array order (Index = i)
var existingById = existingItems.ToDictionary(e => e.Id);
for (var i = 0; i < orderedItems.Count; i++)
{
ReplaceProgramScheduleItem requestItem = orderedItems[i];
ProgramScheduleItem built = BuildItem(programSchedule, i, requestItem);
if (requestItem.Id.HasValue && existingById.TryGetValue(requestItem.Id.Value, out ProgramScheduleItem existing))
{
if (existing.GetType() == built.GetType())
{
// same TPT subtype: copy all scalars in place (BuildItem is the single source of item
// construction, so no field is dropped) and rebuild join rows, keeping the id — and
// with it the fill-group index that would otherwise cascade away. State follows the
// logical item regardless of its new position.
built.Id = existing.Id;
dbContext.Entry(existing).CurrentValues.SetValues(built);
RebuildChildren(existing, requestItem);
}
else
{
// EF can't retype a TPT row in place; replace it. Fill-group state resets and the
// response returns a NEW id (the item fundamentally changed — clients re-sync from it).
dbContext.Remove(existing);
programSchedule.Items.Add(built);
}
}
else
{
// id-less request item → new (unknown ids were already rejected above)
programSchedule.Items.Add(built);
}
}
}
// Unconditional bump: this handler frequently saves with only CHILD changes and no root-scalar
@@ -172,6 +172,7 @@ public class ProgramScheduleHandlerTests
{
AddProgramScheduleItem add = MakeAdd(1, CollectionType.SearchQuery);
return new ReplaceProgramScheduleItem(
null,
index,
add.StartType,
add.StartTime,
@@ -190,6 +190,7 @@ public class ReplaceProgramScheduleItemsHandlerConcurrencyTests
private static ReplaceProgramScheduleItem MakeItem(int index, PlayoutMode mode, string searchQuery) =>
new(
null,
index,
StartType.Dynamic,
StartTime: null,
@@ -3,6 +3,7 @@ using ErsatzTV.Application;
using ErsatzTV.Application.ProgramSchedules;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Scheduling;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
@@ -10,6 +11,7 @@ using LanguageExt;
using Microsoft.EntityFrameworkCore;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Application.ProgramSchedules;
@@ -234,6 +236,329 @@ public class ReplaceProgramScheduleItemsReconcileTests
}
}
[Test]
public async Task Reorder_ById_Should_Move_State_With_The_Logical_Item_Not_The_Slot()
{
// The non-vacuous core of #259: two SAME-typed items are swapped while round-tripping their ids.
// In id-mode each item is matched by id, so idA MOVES to index 1 and keeps its own fill-group state.
// In the old positional reconcile idA would have been reused in place at index 0 (its slot), silently
// pairing item "a"'s enumerator state with item "b"'s content — so `idA.Index == 1` is the assertion
// that fails under positional and passes under id-based reconcile.
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
var seedItems = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.Multiple, "a") with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups },
MakeItem(1, PlayoutMode.Multiple, "b") with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups }
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, seedItems), CancellationToken.None))
.IsRight.ShouldBeTrue();
int idA, idB;
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> persisted = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).OrderBy(i => i.Index).ToListAsync();
idA = persisted[0].Id;
idB = persisted[1].Id;
AddFillGroup(ctx, idA, seed: 100);
AddFillGroup(ctx, idB, seed: 200);
await ctx.SaveChangesAsync();
}
// Act: swap the two items, round-tripping their ids.
var swapped = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.Multiple, "b", id: idB) with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups },
MakeItem(1, PlayoutMode.Multiple, "a", id: idA) with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups }
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, swapped), CancellationToken.None))
.IsRight.ShouldBeTrue();
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> after = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).ToListAsync();
after.Count.ShouldBe(2);
// identity mapping: each id moved to its new position (positional would have kept idA at 0)
after.Single(i => i.Id == idA).Index.ShouldBe(1);
after.Single(i => i.Id == idB).Index.ShouldBe(0);
// each item's fill-group state followed its own id — no misattribution, no cascade
List<PlayoutScheduleItemFillGroupIndex> groups = await ctx.Set<PlayoutScheduleItemFillGroupIndex>()
.Include(x => x.EnumeratorState).ToListAsync();
groups.Single(g => g.ProgramScheduleItemId == idA).EnumeratorState.Seed.ShouldBe(100);
groups.Single(g => g.ProgramScheduleItemId == idB).EnumeratorState.Seed.ShouldBe(200);
}
}
[Test]
public async Task Insert_ById_In_Middle_Should_Keep_Existing_Ids_And_State()
{
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
var seed = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.One, "a"),
MakeItem(1, PlayoutMode.One, "b")
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, seed), CancellationToken.None))
.IsRight.ShouldBeTrue();
int idA, idB;
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> p = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).OrderBy(i => i.Index).ToListAsync();
idA = p[0].Id;
idB = p[1].Id;
AddFillGroup(ctx, idA, seed: 111);
AddFillGroup(ctx, idB, seed: 222);
await ctx.SaveChangesAsync();
}
// insert a brand-new (id-less) item between the two existing ones
var withInsert = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.One, "a", id: idA),
MakeItem(1, PlayoutMode.One, "new"),
MakeItem(2, PlayoutMode.One, "b", id: idB)
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, withInsert), CancellationToken.None))
.IsRight.ShouldBeTrue();
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> after = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).ToListAsync();
after.Count.ShouldBe(3);
after.Single(i => i.Id == idA).Index.ShouldBe(0);
after.Single(i => i.Id == idB).Index.ShouldBe(2); // pushed down by the inserted middle item
List<PlayoutScheduleItemFillGroupIndex> groups = await ctx.Set<PlayoutScheduleItemFillGroupIndex>()
.Include(x => x.EnumeratorState).ToListAsync();
groups.Single(g => g.ProgramScheduleItemId == idA).EnumeratorState.Seed.ShouldBe(111);
groups.Single(g => g.ProgramScheduleItemId == idB).EnumeratorState.Seed.ShouldBe(222);
}
}
[Test]
public async Task Delete_ById_Should_Remove_Unreferenced_And_Keep_Survivor_State()
{
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
var seed = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.One, "a"),
MakeItem(1, PlayoutMode.One, "b")
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, seed), CancellationToken.None))
.IsRight.ShouldBeTrue();
int idA;
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> p = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).OrderBy(i => i.Index).ToListAsync();
idA = p[0].Id;
AddFillGroup(ctx, idA, seed: 333);
await ctx.SaveChangesAsync();
}
// PUT only item A (by id) — B is no longer referenced and must be deleted
var onlyA = new List<ReplaceProgramScheduleItem> { MakeItem(0, PlayoutMode.One, "a", id: idA) };
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, onlyA), CancellationToken.None))
.IsRight.ShouldBeTrue();
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> after = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).ToListAsync();
after.Count.ShouldBe(1);
after.Single().Id.ShouldBe(idA);
// survivor kept its id and its fill-group state (no cascade on the item that stayed)
PlayoutScheduleItemFillGroupIndex survivor = await ctx.Set<PlayoutScheduleItemFillGroupIndex>()
.Include(x => x.EnumeratorState).SingleAsync(g => g.ProgramScheduleItemId == idA);
survivor.EnumeratorState.Seed.ShouldBe(333);
}
}
[Test]
public async Task Unknown_Id_Should_Return_422_And_Persist_Nothing()
{
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
(await handler.Handle(
new ReplaceProgramScheduleItems(scheduleId, [MakeItem(0, PlayoutMode.One, "a")]),
CancellationToken.None))
.IsRight.ShouldBeTrue();
(int idA, int versionBefore) = await ReadSingle(scheduleId);
// a request id that doesn't belong to this schedule is rejected (stale/foreign identity)
var bad = new List<ReplaceProgramScheduleItem> { MakeItem(0, PlayoutMode.One, "x", id: 999999) };
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, bad), CancellationToken.None);
BaseError error = LeftOrThrow(result);
error.GetType().ShouldBe(typeof(BaseError)); // exactly BaseError (→422), not PreconditionFailedError (→412)
error.ToString().ShouldContain("999999");
await AssertUnchanged(scheduleId, idA, versionBefore);
}
[Test]
public async Task Duplicate_Id_Should_Return_422_And_Persist_Nothing()
{
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
(await handler.Handle(
new ReplaceProgramScheduleItems(scheduleId, [MakeItem(0, PlayoutMode.One, "a")]),
CancellationToken.None))
.IsRight.ShouldBeTrue();
(int idA, int versionBefore) = await ReadSingle(scheduleId);
// the same id twice in one payload would map two request items onto one row — reject
var dup = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.One, "a", id: idA),
MakeItem(1, PlayoutMode.One, "a-again", id: idA)
};
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, dup), CancellationToken.None);
BaseError error = LeftOrThrow(result);
error.GetType().ShouldBe(typeof(BaseError));
error.ToString().ShouldContain(idA.ToString());
await AssertUnchanged(scheduleId, idA, versionBefore);
}
[Test]
public async Task Stale_Version_And_Unknown_Id_Should_Return_412_Not_422()
{
// Ordering ruling (§7c): the concurrency pre-check runs before the id guards, so a client that is
// BOTH version-stale and id-stale gets 412 (reload signal), never 422 (which reads as a payload bug).
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
(await handler.Handle(
new ReplaceProgramScheduleItems(scheduleId, [MakeItem(0, PlayoutMode.One, "a")]),
CancellationToken.None))
.IsRight.ShouldBeTrue();
(int idA, int versionBefore) = await ReadSingle(scheduleId);
var bad = new List<ReplaceProgramScheduleItem> { MakeItem(0, PlayoutMode.One, "x", id: 999999) };
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result = await handler.Handle(
new ReplaceProgramScheduleItems(scheduleId, bad, ExpectedVersion: Some(versionBefore + 1)),
CancellationToken.None);
LeftOrThrow(result).GetType().ShouldBe(typeof(PreconditionFailedError));
await AssertUnchanged(scheduleId, idA, versionBefore);
}
[Test]
public async Task Subtype_Change_ById_Should_Replace_That_Item_But_Preserve_A_SameType_Sibling()
{
// id-mode counterpart of the positional Subtype_Change test: in ONE payload, one id-matched item
// changes subtype (One -> Duration: delete+insert, new id, state resets) while a sibling id-matched
// item keeps its subtype (Multiple: in-place, id + fill-group state preserved). This is the riskiest
// reconcile branch — it exercises the delete pass + match-pass Remove/Add without double-handling.
int scheduleId = await SeedSchedule();
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
var seed = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.One, "a"),
MakeItem(1, PlayoutMode.Multiple, "b") with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups }
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, seed), CancellationToken.None))
.IsRight.ShouldBeTrue();
int idA, idB;
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> p = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).OrderBy(i => i.Index).ToListAsync();
idA = p[0].Id;
idB = p[1].Id;
AddFillGroup(ctx, idB, seed: 500); // fill-group state on the same-type sibling
await ctx.SaveChangesAsync();
}
// A (idA) changes subtype One -> Duration; B (idB) stays Multiple.
var changed = new List<ReplaceProgramScheduleItem>
{
MakeItem(0, PlayoutMode.Duration, "a", id: idA) with
{
PlayoutDuration = TimeSpan.FromMinutes(30), DiscardToFillAttempts = 0
},
MakeItem(1, PlayoutMode.Multiple, "b", id: idB) with { FillWithGroupMode = FillWithGroupMode.FillWithShuffledGroups }
};
(await handler.Handle(new ReplaceProgramScheduleItems(scheduleId, changed), CancellationToken.None))
.IsRight.ShouldBeTrue();
await using (TvContext ctx = _db.CreateContext())
{
List<ProgramScheduleItem> after = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).ToListAsync();
after.Count.ShouldBe(2);
// A was replaced: old id gone, a NEW Duration row (distinct id) sits at index 0
after.ShouldNotContain(i => i.Id == idA);
ProgramScheduleItem duration = after.Single(i => i is ProgramScheduleItemDuration);
duration.Id.ShouldNotBe(idA);
duration.Id.ShouldNotBe(idB);
duration.Index.ShouldBe(0);
// B was updated in place: same id, still Multiple, its fill-group state intact
ProgramScheduleItem b = after.Single(i => i.Id == idB);
b.ShouldBeOfType<ProgramScheduleItemMultiple>();
b.Index.ShouldBe(1);
PlayoutScheduleItemFillGroupIndex bState = await ctx.Set<PlayoutScheduleItemFillGroupIndex>()
.Include(x => x.EnumeratorState).SingleAsync(g => g.ProgramScheduleItemId == idB);
bState.EnumeratorState.Seed.ShouldBe(500);
}
}
private static void AddFillGroup(TvContext ctx, int itemId, int seed) =>
ctx.Add(new PlayoutScheduleItemFillGroupIndex
{
PlayoutId = 1,
ProgramScheduleItemId = itemId,
EnumeratorState = new CollectionEnumeratorState { Seed = seed, Index = 0 }
});
private static BaseError LeftOrThrow(Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result) =>
result.Match(Left: e => e, Right: _ => throw new ShouldAssertException("expected a Left error"));
// read the single seeded item's id and the schedule's current version
private async Task<(int Id, int Version)> ReadSingle(int scheduleId)
{
await using TvContext ctx = _db.CreateContext();
int id = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).Select(i => i.Id).SingleAsync();
int version = await ctx.ProgramSchedules
.Where(s => s.Id == scheduleId).Select(s => s.Version).SingleAsync();
return (id, version);
}
// a rejected replace must leave the schedule exactly as it was (no partial write, no version bump)
private async Task AssertUnchanged(int scheduleId, int expectedItemId, int expectedVersion)
{
await using TvContext ctx = _db.CreateContext();
List<int> ids = await ctx.ProgramScheduleItems
.Where(i => i.ProgramScheduleId == scheduleId).Select(i => i.Id).ToListAsync();
ids.ShouldBe([expectedItemId]);
int version = await ctx.ProgramSchedules
.Where(s => s.Id == scheduleId).Select(s => s.Version).SingleAsync();
version.ShouldBe(expectedVersion);
}
private async Task<int> SeedSchedule()
{
await using TvContext ctx = _db.CreateContext();
@@ -249,8 +574,9 @@ public class ReplaceProgramScheduleItemsReconcileTests
return schedule.Id;
}
private static ReplaceProgramScheduleItem MakeItem(int index, PlayoutMode mode, string searchQuery) =>
private static ReplaceProgramScheduleItem MakeItem(int index, PlayoutMode mode, string searchQuery, int? id = null) =>
new(
id,
index,
StartType.Dynamic,
StartTime: null,
@@ -256,6 +256,7 @@ public class ScheduleItemResponseRoundTripTests
private static ReplaceProgramScheduleItem MakeReplace(int index, PlayoutMode playoutMode, CollectionType collectionType) =>
new(
null,
index,
StartType.Dynamic,
StartTime: null,
@@ -299,6 +300,7 @@ public class ScheduleItemResponseRoundTripTests
// response DTO (the SPA does this same field-for-field copy in TypeScript before a PUT).
private static ReplaceProgramScheduleItem ToReplaceCommand(ScheduleItemResponseModel r, int index) =>
new(
r.Id,
index,
r.StartType,
r.StartTime,
@@ -139,7 +139,7 @@ public class ScheduleItemWriteProjectionTests
private static ReplaceProgramScheduleItem ItemWithGraphics(int index) =>
new(
index, StartType.Dynamic, StartTime: null, FixedStartTimeBehavior: null, PlayoutMode.One,
null, index, StartType.Dynamic, StartTime: null, FixedStartTimeBehavior: null, PlayoutMode.One,
CollectionType.Collection, CollectionId: 1, MultiCollectionId: null, SmartCollectionId: null,
RerunCollectionId: null, MediaItemId: null, PlaylistId: null, SearchTitle: null, SearchQuery: null,
PlaybackOrder: PlaybackOrder.Shuffle, MarathonGroupBy: MarathonGroupBy.None,
@@ -403,6 +403,7 @@ public class ScheduleControllerTests
private static ScheduleItemRequest MakeItemRequest(PlayoutMode playoutMode) =>
new(
Id: null,
StartType.Dynamic,
StartTime: null,
FixedStartTimeBehavior: null,
@@ -143,6 +143,7 @@ public class ScheduleItemTptIntegrationTests
{
AddProgramScheduleItem add = MakeAdd(1, playoutMode);
return new ReplaceProgramScheduleItem(
null,
index,
add.StartType,
add.StartTime,
@@ -4,7 +4,14 @@ using ErsatzTV.Core.Scheduling;
namespace ErsatzTV.Controllers.Api.Requests;
/// <param name="Id">
/// Server-assigned identity of an existing schedule item, as returned by GET /api/schedules/{id}/items.
/// Omit (or send null / 0) for a new item. On a replace, the item carrying this id keeps its persisted
/// fill-group/shuffle progression even when moved to a different position. Unknown or duplicated ids are
/// rejected with 422 — never fabricate an id.
/// </param>
public record ScheduleItemRequest(
int? Id,
StartType StartType,
TimeSpan? StartTime,
FixedStartTimeBehavior? FixedStartTimeBehavior,
@@ -86,6 +93,9 @@ public record ScheduleItemRequest(
public ReplaceProgramScheduleItem ToReplaceCommand(int index) =>
new(
// normalize the two-state client value (null / 0 / positive) to the handler's null-or-real
// contract so 0-defaulting clients read as "new item" rather than "existing item 0"
Id is > 0 ? Id : null,
index,
StartType,
StartTime,
+8
View File
@@ -24363,6 +24363,7 @@
},
"ScheduleItemRequest": {
"required": [
"id",
"startType",
"startTime",
"fixedStartTimeBehavior",
@@ -24403,6 +24404,13 @@
],
"type": "object",
"properties": {
"id": {
"type": [
"null",
"integer"
],
"format": "int32"
},
"startType": {
"$ref": "#/components/schemas/StartType"
},
+32
View File
@@ -424,6 +424,38 @@ making it explicit is optional cleanup, not required. Config handlers that commi
`IConfigElementRepository.Upsert` calls are a distinct partial-commit-under-cancellation case not covered
by this rule (tracked separately).
## 7c. Stable child identity in replace lists (schedule items)
§7 indexes replace-list children by **array order**, which is the reconcile *key* for most replace PUTs.
That is correct only when a child row is pure config: reordering merely re-numbers otherwise-interchangeable
rows. **Schedule items are the exception** (issue #259): a schedule item anchors persisted runtime state —
`PlayoutScheduleItemFillGroupIndex` (fill-group / shuffle enumerator progression) FKs the item row with
`OnDelete(Cascade)`. Reconciling those by position makes a **moved** item inherit the state of whatever item
previously occupied its new slot. So `PUT /api/schedules/{id}/items` carries a stable child identity:
- `ScheduleItemRequest.Id` (`int?`) round-trips each existing item's server id (as returned by the items GET).
**null / absent / 0 ⇒ a new item** (the controller normalizes `0`→null so the handler contract is
two-state). Never fabricate an id.
- When **any** request item carries an id, `ReplaceProgramScheduleItemsHandler` reconciles **by id**: matched
same-subtype rows are updated in place (keeping the id, so the fill-group index never cascades and follows
the logical item across reorders/inserts); a matched row whose TPT subtype changed is delete+insert (state
resets, a **new id is returned** — clients must re-sync from the PUT response); unreferenced existing rows are
deleted; id-less request items are inserted. `Index` is still array-position (ordering is a separate axis
from identity).
- **A fully id-less payload falls back to the verbatim positional reconcile** (legacy clients). This preserves
today's misattribution-on-reorder for such payloads — it is temporary and retires together with the §7a
Phase-2 `If-Match`→428 flip.
- **Guards run inside the handler, after the §7a `CheckVersion`** (so a client that is both version-stale and
id-stale gets **412**, the reload signal, not 422): a duplicate id in one payload → **422**; an id not
belonging to this schedule → **422** (under Phase-1 force-write a stale id is a live lost-update signal, not
a new item — reject rather than silently duplicate). Both persist nothing.
**Deliberate asymmetry**: the other positional replace handlers (blocks #2, templates #3, deco-templates #4,
playlists #5) do **not** carry a child id — their children are stateless config rows where positional churn is
unobservable (#3/#4 don't even emit a child id on GET). Child ids are added only where a child row anchors
server-side state; positional replace stays the default. A per-endpoint child-id contract can be retrofitted
later without breaking anything (the field stays optional).
## 8. Known API warts (don't "fix" without discussion — they're deliberate synthesized rows)
`GET /api/blocks` and `GET /api/templates` (via `GetAllBlocksHandler` / `GetAllTemplatesHandler` in
+24
View File
@@ -890,3 +890,27 @@ Also removed the now-dead ersatztv#25 razor-Sonar `<NoWarn>S6966;S3267;…</NoWa
**Rollback.** The tag `blazor-final` was cut on the pre-removal `main` commit as the first step (see the
2026-07-11 "Pre-removal Blazor rollback tag `blazor-final` (#205)" entry above for the exact command +
restore path). Not a `v*` tag → no prod release build.
## 2026-07-11 — Stable child identity for schedule-item replace (#259, split from #252/#253)
`PUT /api/schedules/{id}/items` now reconciles by an optional round-tripped child id, not by 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 held its new slot. Contract + rules in **api-conventions §7c**. Key decisions:
- **`ScheduleItemRequest.Id` (`int?`)**: null/absent/`0` ⇒ new item (controller normalizes `0`→null so the
handler is two-state). Any id present ⇒ id-based reconcile; a fully id-less payload keeps the verbatim
positional fallback (legacy; retires with the §7a Phase-2 `If-Match`→428 flip).
- **Unknown or duplicate id ⇒ 422, nothing persisted**; the guards live in the handler **after** §7a
`CheckVersion`, so **412 precedes 422** — a client that is both version-stale and id-stale gets the reload
signal, not a payload-bug signal. Rationale for reject-not-insert on an unknown id: under Phase-1
force-write a stale id is a live lost-update signal, so silently inserting-as-new would duplicate the item
and return a different id than the client sent (the exact class §7a exists to surface). This is also the
correct #197 posture — never honor an unrecognized identifier.
- **Scope = schedule items only.** Blocks/templates/deco-templates/playlists stay positional: their children
are stateless config rows (no FK'd state to misattribute; #3/#4 have no GET child id). Child ids are added
only where a child row anchors server-side state; the contract can be retrofitted per-endpoint later
(field stays optional) — so this is not #197 ossification pressure.
- **TPT subtype change at a matched id** stays delete+insert (EF can't retype in place); state resets and a
new id is returned, so the SPA must re-seed item state from the PUT response (a stale id on a second save
now 422s).
+1
View File
@@ -1279,6 +1279,7 @@ export interface components {
"deepScan"?: boolean;
};
"ScheduleItemRequest": {
"id": null | number;
"startType": components["schemas"]["StartType"];
"startTime": null | string;
"fixedStartTimeBehavior": null | components["schemas"]["FixedStartTimeBehavior"];
+8 -4
View File
@@ -57,10 +57,14 @@ export function addScheduleItem(scheduleId: number, body: ScheduleItemRequest):
return request<ScheduleItem>(`/api/schedules/${scheduleId}/items`, { body, method: 'POST' });
}
// Positional in-place reconcile: the server reuses same-typed item rows (keeping fill-group state) and
// triggers playout rebuilds. The editor batches all local draft edits into this single call. Pass the
// last-seen ETag as `If-Match` to reject a stale overwrite with 412; the resolved value carries the new
// ETag for a subsequent save (issue #253). See docs/decisions.md.
// Id-based reconcile (#259): each item's `id` (round-tripped from the GET response by the editor;
// `null` for a new/copied item never persisted) tells the server which existing row to update in place
// vs. insert, so fill-group/shuffle state on an existing row survives a reorder. The editor batches all
// local draft edits into this single call. Pass the last-seen ETag as `If-Match` to reject a stale
// overwrite with 412; the resolved value carries the new ETag for a subsequent save (issue #253). See
// docs/decisions.md. Note: switching an item's playout-mode/subtype can be a delete+insert server-side,
// so the response's ids may differ from what was sent — the editor must re-seed its draft from the PUT
// response (see SchedulesScreen.tsx `save()`), not reuse the ids it submitted.
export function replaceScheduleItems(
scheduleId: number,
body: ReplaceScheduleItemsRequest,
@@ -14,6 +14,7 @@ const schedules = [
// Mirrors AddProgramScheduleItem.ForMediaItem defaults (AddProgramScheduleItem.cs:48-87), with the
// mapped collectionType + mediaItemId for a TelevisionShow item.
const expectedShowPayload = {
id: null,
startType: 'Dynamic',
startTime: null,
fixedStartTimeBehavior: null,
+1
View File
@@ -34,6 +34,7 @@ export function scheduleItemRequestForMediaItem(
mediaItemId: number
): ScheduleItemRequest {
return {
id: null,
startType: 'Dynamic',
startTime: null,
fixedStartTimeBehavior: null,
+15
View File
@@ -349,10 +349,14 @@ describe('factories', () => {
graphicsElementIds: []
});
expect(item._key).toMatch(/^draft-/);
// A never-persisted item must not carry a server id (#259) — the save projection relies on this
// to tell the server it's an insert.
expect(item.id).toBeNull();
});
it('copyDraftItem deep-copies multi/smart/rerun refs and gives a new key + array identity', () => {
const original = draft({
id: 99,
multiCollectionId: 3,
multiCollectionName: 'M',
smartCollectionId: 4,
@@ -372,6 +376,9 @@ describe('factories', () => {
expect(copy.watermarkIds).toEqual([1, 2]);
expect(copy.watermarkIds).not.toBe(original.watermarkIds);
expect(copy.graphicsElementIds).not.toBe(original.graphicsElementIds);
// A copy is a new row that was never persisted under its own id — it must not carry the source
// item's server id (#259), or a save would submit the same id twice.
expect(copy.id).toBeNull();
});
});
@@ -438,6 +445,9 @@ describe('fromResponse', () => {
durationEstimate: '01:00:00'
};
const item = fromResponse(model);
// The server id must round-trip onto the draft (#259) so a subsequent save reconciles this row by
// identity instead of by array position.
expect(item.id).toBe(42);
expect(item.smartCollectionId).toBe(7);
expect(item.smartCollectionName).toBe('Smarts');
expect(item.watermarkIds).toEqual([1, 2]);
@@ -500,6 +510,11 @@ describe('normalizeForSave', () => {
expect('collectionName' in req).toBe(false);
expect('name' in req).toBe(false);
});
it('passes the draft id through unchanged: null for a new item, the server id for a loaded one (#259)', () => {
expect(normalizeForSave(draft()).id).toBeNull();
expect(normalizeForSave(draft({ id: 42 })).id).toBe(42);
});
});
describe('validation', () => {
+12
View File
@@ -253,6 +253,9 @@ export function applyPlayoutModeChange(item: DraftItem, newMode: PlayoutMode): D
export function newDraftItem(): DraftItem {
return {
_key: nextDraftKey(),
// Never round-tripped from the server — the save projection must emit `id: null` for this item so
// the server treats it as an insert rather than colliding with (or misattributing) an existing row.
id: null,
startType: 'Dynamic',
startTime: null,
fixedStartTimeBehavior: null,
@@ -308,6 +311,9 @@ export function copyDraftItem(item: DraftItem): DraftItem {
return {
...item,
_key: nextDraftKey(),
// The copy is a new, never-persisted row — it must not carry the source item's server id, or the
// save projection would submit the same id twice (server would treat the copy as the same row).
id: null,
watermarkIds: [...(item.watermarkIds ?? [])],
graphicsElementIds: [...(item.graphicsElementIds ?? [])]
};
@@ -318,6 +324,9 @@ export function copyDraftItem(item: DraftItem): DraftItem {
export function fromResponse(model: ScheduleItem): DraftItem {
return {
_key: nextDraftKey(),
// Round-trip the server id so a subsequent save reconciles this row by identity (#259) rather
// than by array position.
id: model.id,
startType: model.startType,
startTime: model.startTime,
fixedStartTimeBehavior: model.fixedStartTimeBehavior,
@@ -379,6 +388,9 @@ export function normalizeForSave(item: DraftItem): ScheduleItemRequest {
const fillWithGroupMode = fillWithGroupModeEligible(item) ? item.fillWithGroupMode : 'None';
return {
// null for a draft item never round-tripped from the server (new / copied) — the server treats a
// null id as an insert. A non-null id reconciles the existing row by identity (#259).
id: item.id,
startType: item.startType,
startTime: isFixed ? item.startTime : null,
fixedStartTimeBehavior: isFixed ? item.fixedStartTimeBehavior : null,
+27 -2
View File
@@ -203,6 +203,10 @@ describe('SchedulesScreen — draft mutations issue a single PUT on Save', () =>
// exactly one PUT, and no POST/DELETE to items endpoints
expect(handle.requests.filter((r) => r.method === 'PUT' && r.url === '/api/schedules/1/items')).toHaveLength(1);
expect(handle.requests.filter((r) => r.url.includes('/items/'))).toHaveLength(0);
// #259: the pre-existing item (loaded via GET, id 10) round-trips its server id; the brand-new item
// (added in the editor, never persisted) sends a null id so the server treats it as an insert.
expect(items[0].id).toBe(10);
expect(items[1].id).toBeNull();
});
it('edit a field → PUT reflects it', async () => {
@@ -214,9 +218,9 @@ describe('SchedulesScreen — draft mutations issue a single PUT on Save', () =>
expect(lastPut(handle)[0].customTitle).toBe('Nightly');
});
it('copy item deep-copies references into the PUT payload', async () => {
it('copy item deep-copies references into the PUT payload, but the copy sends a null id', async () => {
const handle = await renderReady({
items: [responseItem({ collectionType: 'MultiCollection', collectionId: null, multiCollectionId: 8, multiCollectionName: 'Multi', playbackOrder: 'Shuffle', name: 'Multi' })]
items: [responseItem({ id: 10, collectionType: 'MultiCollection', collectionId: null, multiCollectionId: 8, multiCollectionName: 'Multi', playbackOrder: 'Shuffle', name: 'Multi' })]
});
fireEvent.click(screen.getByRole('button', { name: /Copy Multi/ }));
fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
@@ -225,6 +229,27 @@ describe('SchedulesScreen — draft mutations issue a single PUT on Save', () =>
expect(items).toHaveLength(2);
expect(items[0].multiCollectionId).toBe(8);
expect(items[1].multiCollectionId).toBe(8);
// The original round-trips its server id; the copy is a new row that was never persisted under its
// own id, so it must not send the original's id (#259) — that would collide with it server-side.
expect(items[0].id).toBe(10);
expect(items[1].id).toBeNull();
});
it('re-seeds ids from the PUT response so a second save reuses the fresh ids (#259)', async () => {
const handle = await renderReady();
const title = screen.getByLabelText('Custom title') as HTMLInputElement;
fireEvent.change(title, { target: { value: 'First edit' } });
fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
await waitFor(() => expect(handle.requests.filter((r) => r.method === 'PUT').length).toBe(1));
// The mock echoes the submitted item back with a new id (500 + index) — simulating a server-side
// delete+insert reconcile. The editor must adopt that id, not keep serving the id it submitted.
const titleAfterSave = screen.getByLabelText('Custom title') as HTMLInputElement;
fireEvent.change(titleAfterSave, { target: { value: 'Second edit' } });
fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
await waitFor(() => expect(handle.requests.filter((r) => r.method === 'PUT').length).toBe(2));
const secondPut = lastPut(handle);
expect(secondPut[0].id).toBe(500);
expect(secondPut[0].customTitle).toBe('Second edit');
});
it('remove item → PUT omits it', async () => {
+5
View File
@@ -334,6 +334,11 @@ export function SchedulesScreen() {
// Load-bearing: a same-tab second save must use the ETag this write produced, or it would 412
// against its own change (#253).
etagRef.current = etag;
// Also load-bearing for #259: re-seed the draft's ids from the PUT response, not the ids that
// were submitted. A subtype/playout-mode switch can be a delete+insert server-side, so the
// response id for that row can differ from what was sent; fromResponse captures response.id
// onto each draft, so a subsequent save reconciles by the now-current id instead of a stale one
// (which the server would 422 as unknown).
const drafts = [...response].sort((a, b) => a.index - b.index).map(fromResponse);
baselineRef.current = drafts;
setItems(drafts);