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.3 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| security.contract-freeze-honesty | 2026-07-12 (#197 Bundle C — contract-freeze honesty) | active | 2026-07-12 | none | none | The OpenAPI doc's declared security/401 scheme is generated from the same `ApiKeyAuthorizationFilter.EndpointRequiresKey` predicate the runtime enforces (so declared auth can't drift from enforced auth), every `/api/*` action returns a ResponseModel (no raw Application VMs), and Channel REST resources are keyed by immutable `Id`, never mutable `Number`. | OpenAPI contract honesty, ResponseModel wrapping, Id vs Number key · paths: `OpenApiContractHonestyTests`, `ErsatzTV.Core/Api` · issues: #197, #287, #288 | `OpenApiContractHonestyTests`; `docs/api-conventions.md` |
#287 — OpenAPI contract honesty by construction. The "v1" document now emits the ApiKey security
scheme plus per-operation security/401 derived from the same
ApiKeyAuthorizationFilter.EndpointRequiresKey predicate the runtime filter enforces, so declared auth
can never drift from enforced auth. Every operation also gets a synthesized stable operationId (the
framework only assigned one when Name= was set — ~90 were missing), and body/param-binding operations
get the documented 400 ValidationProblemDetails they actually return. DayOfWeek is now a string enum
in the schema (added to Startup.UseStringEnumSchemas), removing the SPA's WithDayNames wart. Pinned by
in-process document generation in tests (OpenApiContractHonestyTests) rather than the committed v1.json.
#288 — Wrap the last raw ViewModels; reverse the §7a "intentional version leak." Minted
MediaCollectionResponseModel, ProgramScheduleResponseModel, and ChannelDetailResponseModel (all
#nullable enable) and routed CollectionController / ScheduleController / SmartCollectionController /
ResolutionController.GetResolutionByName / the channel detail GET+writes through ResponseModels, so no
/api/* action returns an Application VM. This reverses the earlier §7a judgment that a ResponseModel
"purely to hide one field was disproportionate": Version is now header-only (ETag) on every aggregate
body — confirmed safe by grepping web/src (the SPA reads version from the ETag header, never the
response body). ChannelDetailResponseModel is the full editable field set the channel editor needs
(distinct from the lean list ChannelResponseModel; drops only the derived webEncodedName). Also flipped
#nullable enable onto the remaining 24 lagging ErsatzTV.Core/Api/ files for schema honesty, and added
pageNum paging to GET /api/search.
Channel REST resources are keyed by database Id, never by Number. Channel.Number is user-mutable
(editable on update, bulk-renumbered via /api/channels/bulk/renumber, transiently invalid mid-renumber),
so the immutable int PK is the canonical key for all /api/channels/* single-item routes, sub-resources
(including playout/reset, re-keyed from {channelNumber} to {id:int} in Bundle C), and Location
headers. Number remains the identity on broadcast surfaces only (IPTV/M3U/XMLTV), a separate contract. A
number-based lookup endpoint may be added additively later; UniqueId (Guid) stays out of the REST
contract absent a federation requirement.