timothy
fba5233caf
168 records -> docs/decisions/records/<area>/<topic>.md (163 active, 23 dirs) and docs/decisions/archive/<area>/<topic>.md (5 archived). The filename IS the key, so one-active-record-per-key becomes a filesystem property rather than a validator check, and supersession becomes a `git mv`. WHY: the monolith was a concurrency problem before an aesthetic one. A 3,900-line append target made parallel sessions collide -- PR #605 and PR #614 both hit append-vs-append conflicts during routine rebases, and hand-resolving those inside the corpus is exactly the operation the rationale-rewrite guard exists to police. HOW IT IS VERIFIED: a ~170-file diff cannot be meaningfully read, so correctness does not rest on reading it. The parser was taught BOTH formats first, so the body-diff guard parses the old form at the merge-base and the new form at head -- the migration validates itself, no bypass. The proof is a field-level equivalence harness: 168 records before and after, zero lost, zero gained, zero field mismatches, zero rationale bodies differing. Reviewers should scrutinise the harness; it is the actual evidence. What measuring caught that reading would not have: - ~500 lines sit OUTSIDE any record -- decisions.md's lifecycle schema and each topic file's preamble, mostly the only copy. Source files are kept and stripped, never deleted. They also cannot be filed per-area: topic files hold several areas and 4 of 23 areas span several files. - Archive discovery was a non-recursive glob; after the split it found ZERO archived records, surfacing as four bogus "supersedes points to unknown key" errors rather than an obvious failure. - ~32 live docs point into the corpus BY DATE, which the split dangles. Each stripped file now ends with a generated "Records formerly in this file" index, which also rescues the identical breadcrumbs in old issue comments. - decisions.md's "In this file:" list was 97 same-file anchor bullets that the split makes WRONG, not merely stale. Dropped; the generated index replaces them with links that resolve. The equivalence harness now runs against a checked-in FIXTURE, not the live corpus. The earlier version migrated the real tree, which made it a one-shot: the moment the migration landed there was nothing left to move and the tests failed for reasons unrelated to the code. A fixture keeps them testing the SCRIPT rather than the repo's current state. Keys preserved verbatim, warts included: `sched` (12) and `scheduling` (1) remain two directories for one concept. Renaming a key is not a move -- it changes identity, breaks the equivalence proof, and invalidates MemPalace's per-key drawers. Taxonomy normalisation is separate work. refs #610
3.4 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| api.playout-build-lock-409 | 2026-07-10 — Playout API mutations return 409 while the build lock is held (#215) | active | 2026-07-10 | none | none | Every id-keyed playout/channel mutation endpoint checks `IEntityLocker.IsPlayoutLocked(id)` and returns 409 Conflict while a build is in-flight, mirroring Blazor's disabled-buttons behavior; reset-all stays 202 and silently skips locked playouts. | `ApiResults.ConflictProblem`, `PlayoutListItemResponseModel.IsLocked`, advisory check-then-act · paths: `PlayoutController.cs`, `ChannelController.cs` · issues: #215, adversarial-reviewer#18 | `ApiResults.ConflictProblem` |
Blazor disabled per-playout Reset/Erase/Delete/Edit while a BuildPlayout was in flight
(EntityLocker.IsPlayoutLocked, Playouts.razor + per-kind editors); the REST API had no
equivalent, so a client could race an in-flight build with a destructive ExecuteDelete and leave
a half-built playout. Adversarial-reviewer#18 promoted this to a #91-phase-(b) removal gate: after
Blazor is deleted the invariant would vanish entirely.
Decision: enforce the invariant server-side on the API rather than re-implementing a live push
channel. PlayoutController and ChannelController inject IEntityLocker; every id-keyed mutation
— PUT /api/playouts/{id}, .../deco, .../alternate-schedules, .../templates,
POST .../erase-items, .../erase-items-and-history, DELETE /api/playouts/{id}, and
POST /api/channels/{channelNumber}/playout/reset — checks IsPlayoutLocked(id) first and returns
409 Conflict (ApiResults.ConflictProblem, new shared helper mirroring NotFoundProblem) while
the build lock is held. The PUTs are gated too (not just the destructive ops): the target invariant
is "no mutation during a build", matching Blazor's edit-disable.
-
The guard is advisory check-then-act, not mutual exclusion — same posture as Blazor's disabled buttons. A
BuildPlayoutalready sitting in the worker queue can take the lock a few milliseconds after the check passes, so the original race is narrowed, not eliminated; consequences remain self-healing (the next rebuild corrects a half-mutated playout). True prevention — having each mutation acquire the playout lock for its duration — was deliberately not taken:LockPlayoutpublishesPlayoutUpdatedNotification(UI churn per mutation) and would make mutations block builds, a semantics change out of scope for restoring Blazor parity. -
reset-allis deliberately NOT gated — it stays 202.ResetAllPlayoutsHandleralready silently skips locked playouts, which matches Blazor and the handler semantics; a fire-and-forget bulk enqueue always accepts. -
SPA mirrors the lock via data, not a push channel —
PlayoutListItemResponseModelgains anIsLockedbool (set fromIsPlayoutLockedin the controller's list projection). The playouts screen disables Reset/Erase/Erase-and-history/Delete for a locked row and shows a "Building…" Badge; on a 409 from any mutation it surfaces the error and callsquery.refresh()so the row picks up the flag. No new polling was added (the existing 30s channel-state poll is unchanged).
Precedent for the 409 shape: TraktController (left as-is with its own private ConflictProblem()
to keep the diff small). Convention recorded in api-conventions.md §3a.