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
4.2 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| concurrency.diff-scalar-fanout | 2026-07-11 — #253 PR3: Diff + Scalar concurrency fan-out (Collection / Playout×2 / MultiCollection / RerunCollection) | active | 2026-07-11 | none | none | The frozen Block optimistic-concurrency recipe (api-conventions §7a) fans out to Collection/Playout×2/MultiCollection/RerunCollection, keeping a guard-returned `PreconditionFailedError` out of any handler's generic `catch(Exception)`→422 mapping, and preserving each aggregate's existing `SaveChangesAsync() > 0` gate semantics under the new unconditional `Version++`. | concurrency fan-out, PreconditionFailedError, SaveChangesWithConcurrencyGuard · paths: `api-conventions.md` §7a · issues: #253, #269, #232, #197 | `RootWriterForceVersionTests`-adjacent handler tests; `api-conventions.md` §7a |
Context. PR3 of the #253 optimistic-concurrency arc fans the frozen Block recipe (api-conventions §7a) across the five Diff/Scalar aggregates. Three judgment calls beyond the mechanical copy:
H1 — Playout catch(Exception)→422. The two Playout replace handlers wrap SaveChangesAsync in a
catch(Exception) that maps any exception to a bare BaseError (→ 422). Rather than let the guard's
concurrency failure be reshaped into a 422, the guarded save (SaveChangesWithConcurrencyGuard) returns a
PreconditionFailedError Left as a value and the handler returns it before the post-commit block —
so it never reaches the catch. Proven by the pre-check-subtype tests (a .Apply flatten would fail
ShouldBeOfType<PreconditionFailedError>) plus a non-vacuous Playout racing-save test.
M2 — the SaveChangesAsync() > 0 gates. RerunCollection and Collection-custom-order run their
playout-refresh unconditionally on a successful save (the unconditional Version++ makes the old gate
always-true; the "nothing changed" branch is dead). MultiCollection is the exception: it saved the name
first specifically so a name-only change wouldn't rebuild playouts, so we bump Version on that first
save and leave the second (items) save's > 0 gate intact — a name-only edit still bumps + rotates the
ETag but does not rebuild. Enumerating every behavior the gate provided before reworking it (the #232 lesson).
Sibling-writer scope (deferred). §7a's config-only boundary says every writer of an aggregate's
editor-visible config bumps Version. PR3 ships the five primary endpoints' full contract + the one
design-named bulk writer (UpdateDefaultDecoHandler, safe via .SetProperty). It defers the other
same-root non-bulk config writers (UpdateCollectionHandler, RemoveItemsFromCollectionHandler,
UpdatePlayoutHandler, the ScheduleFile handlers) and the repository-mediated Add*ToCollection family.
Rationale: the primary endpoints' own bump+guard fully cover the two-tab lost-update the issue targets;
the deferred writers only affect cross-editor ETag rotation, and adding an unconditional bump to a handler
that uses plain SaveChangesAsync (not the guard) converts a latent lost-update into a new 500
(DbUpdateConcurrencyException) — doing it safely needs a uniform guard+bump+412 pass of its own, better
done with the #197 contract work. Tracked as a follow-up issue.
VMs. Playout.Version surfaces via PlayoutNameViewModel (required arg); the three collection VMs
(MediaCollectionViewModel, MultiCollectionViewModel, RerunCollectionViewModel) carry int Version = 0
(defaulted — 0 for the selection-placeholder constructions, real value from the Mapper projection).
Header-only via ETag, never echoed in a response body (the Block precedent).
Post-merge addendum (PR3 review, #269). Activating the Version token means EF guards every root
UPDATE, so non-participating root-scalar writers that use plain SaveChangesAsync (playout settings /
schedule-file / on-demand-checkpoint, collection name) would 500 on a concurrent bump. The realistic
UPDATE writers were fixed in-PR with ConcurrencyExtensions.SaveChangesForcingVersion (Phase-1
force-write on conflict: adopt the stored token, retry, never revert the concurrent bump). The deferral
above is re-scoped to the DELETE handlers + repository Add* writers only (→ #269).