87 Commits

Include renames

Author	SHA1	Message	Date
timothyandClaude Fable 5.1	16a6e2790f	test(563): bind the fixture with the production body binder, and name the wrapper that is left ... The docstring, the decision record and docs/testing.md all claimed the replay covered everything except two hops. MVC model binding was a third: production binds /api/* bodies with Newtonsoft (Startup -> AddNewtonsoftJson -> CustomContractResolver + StringEnumConverter) while the replay deserialized with System.Text.Json. Measured on this tree: for the fixture's own bodies the two agree, but for a body omitting the `required` member "collection" they diverge -- System.Text.Json throws, Newtonsoft binds Collection = null and the action runs. So the fixture's stated purpose ("field names and casing match what the HTTP body binder accepts") was asserted by nothing, and a fixture production would bind differently could still go green. Rather than only widening the residue list, bind the way production binds. The registration moves into ErsatzTV/Serialization/ApiJsonSettings.cs, Startup applies it from there, and both OpenApiSerializerContractTests (which had its own mirror of the settings) and the scripted replay now call that same function -- one definition, no copies to drift. Production_Body_Binder_Ignores_Required_Members asserts both halves of the divergence THROUGH the replay's own Bind helper, so pointing the replayer at another serializer reddens; the fixture's own bodies cannot witness that swap. The residue is now named honestly in all four places: the binding WRAPPER (input formatter, the [ApiController] automatic 400 before an action runs) is uncovered, the serializer inside it is not. Decisions-Edit: yes Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV	2026-09-05 09:25:11 +02:00
timothyandClaude Opus 5	528383cf3a	fix(880): an absent recurrence array means unrestricted, an explicit [] is rejected (#892) ... The three recurrence arrays are read CONJUNCTIVELY by AlternateScheduleSelector.GetScheduleForDate, so an empty set matches no date. `?? []` on an omitted array therefore returned HTTP 200 while storing an alternate-schedule or template item that could never apply, silently -- while the read side (#823) already read a NULL column as the All*() sets. Absent and explicitly-empty are two different requests and get two answers: ABSENT (missing, or explicit null) normalizes to AlternateScheduleSelector.All*(), the same symbols the read side substitutes; EXPLICIT [] is rejected with a 422 naming the consequence, via RecurrenceSetBounds called from both replace handlers. The rejection lives in the handlers, not the controller, because api.ffmpeg-profile-numeric-bounds' "accept an UNCHANGED bad value" rule binds hardest here: both PUT paths are whole-list replaces, so rejecting a pre-existing empty set would make every OTHER item in the list uneditable. That comparison needs the stored row. The validated set is derived from `incoming`, so the highest-Index catch-all -- whose recurrence the handler discards -- is excluded by construction. Verified: full ErsatzTV.Tests suite green; three mutation proofs with disjoint reddened sets; live-E2E against a real instance confirmed an OMITTED property round-trips as unrestricted (the Newtonsoft missing-property chain unit tests cannot reach), an explicit [] returns the 422, and [] on the catch-all is accepted. Cross-family cold review BLOCKED the first implementation with 3 findings, all real and all fixed; re-review returned MERGEABLE. Follow-up #894 filed: the SPA can still build the empty state the server rejects. fixes #880 Decisions-Edit: yes Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-08-30 09:29:02 +00:00
timothyandtimothy	ed8b602445	feat(735): bound the numeric FFmpeg profile fields with a 422, and expose readrate pacing (#847) ... Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>	2026-08-26 22:05:38 +00:00
timothyandtimothy	08cd3a002d	fix(690,758): count the same query a paged handler pages (#833) ... Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>	2026-08-26 07:39:23 +00:00
timothyandClaude Opus 5	572737a29e	fix(671): review round 2 -- guard Song.Artists, cover the second consumer ... Cold independent review of 017ef988d. Three findings taken, one filed out. The important one is a regression this branch INTRODUCED. `SongMetadata.Artists` is a nullable EF primitive collection (JSON in one column, not a navigation) that FallbackMetadataProvider leaves unassigned when a song's tags fail to read, and `string.Join` throws ArgumentNullException on a null sequence. The rerun list previously did not load SongMetadata at all, so the throw was unreachable there; adding the include promoted it to a live 500 that would have failed the whole page. Confirmed by reverting the guard: ArgumentNullException, parameter 'values'. The file header claiming every member was guarded was false. The empty case is filtered too, so an artist-less song loses its bare " - ". Second: `GetPlaylistItemsHandler` had no handler-level test at all (its controller tests stub the mediator), so the RemoteStream include added last round was discharged by inspection -- the same method that produced #671. It now runs the same 13-type matrix via a shared SelectionSeedData; removing the include fails that matrix. Third: dropped the dead `(i as Season).SeasonMetadata` include leg -- the Season projection reads Show.ShowMetadata and the scalar SeasonNumber, never SeasonMetadata. Filed #690 for the pre-existing, out-of-scope finding: the paged TotalCount ignores the search query, so the SPA renders empty pages. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 19:33:52 +02:00
timothyandClaude Opus 5	8523088ceb	fix(671): resolve rerun-collection selections through one shared include chain ... The paged list handler eager-loaded nothing, so `ProjectToViewModel` read four unloaded navigations and every row of every collection type projected a null selection. Because the selected id and the display name are read off the SAME navigation, this dropped the id too -- the harm is not an unlabelled badge but an editor that round-trips a null and clears the user's stored selection. The by-id handler loaded metadata for only four of the ten selectable media types: Song/OtherVideo/Image/RemoteStream returned a null-ish selection and Episode/MusicVideo threw an NRE that surfaced as a 500. Fixed at the boundary rather than per call site: - `RerunCollectionQueryExtensions.IncludeSelectionDetails()` is now the single include chain, called by both handlers, joining the existing `ProgramScheduleItemQueryExtensions.IncludeScheduleItemDetails()` precedent (#229). Artwork legs are deliberately omitted -- this projection reads only ids and titles. - The media-item switch was duplicated verbatim for RerunCollection and PlaylistItem; both now call one `ProjectMediaItemToViewModel`, which handles `RemoteStream` (via a new `ProjectToNamedViewModel`, since the existing `ProjectToViewModel(RemoteStream)` returns an unrelated type) and never falls through to null -- an unknown subtype keeps its id and takes a conspicuous name, because throwing would fail a whole paged GET over one bad row. - Every metadata navigation in `MediaItems.Mapper` is now read through `Optional(...).Flatten()`, so an un-included nav degrades to "???" instead of being a latent 500 for whichever caller loads least. Tests enumerate all 13 supported CollectionTypes for both handlers, with the matrix derived from `IsSupportedSelectionType` so a newly-supported type joins it automatically, plus a completeness guard on the set. Each mechanism was removed in turn and confirmed red first. fixes #671 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 18:48:24 +02:00
timothy	fc3ede09bc	docs(578): the retracted claim survived in 9 places, including the record title and rule ... Comment- and docs-only; verified no non-comment line changed in any .cs. I reported last round that I had "classified every surviving hit". That was false, and the false confidence is the expensive part: a confidently-stated "I checked everything" stops anyone else checking. The retracted wording survived in nine places, two of them the record's title and rule: — and the catalog copies rule: verbatim, so the generated entry point and the record disagreed semantically while docs/decisions.md said the correct thing. Root cause of the miss, because it will recur otherwise: I built the sweep term list from the DELETED MECHANISM's vocabulary (LIKE, superset, keyspace, anchor, over-match) and never added the RETRACTED CLAIM's own words. "no predicate", "bound on work", "index entries", "no gap" and "holds in memory" were never grepped. After a retraction the subject list has to include the words of the thing being retracted, not just the thing already deleted. Second, worse: my first attempt at this round's sweep printed nothing for every term and I nearly read that as "all clear". zsh does not word-split an unquoted $FILES, so grep received one giant non-existent path — and the `|| echo "(none)"` never fired because the pipeline's exit status was sed's. Same failure shape as the bug arc itself: a check reporting success while examining nothing. Re-run with a proper array plus a control term ("SongMetadata" -> 42 hits) so an empty result is distinguishable from a broken grep. Fixed all nine, replacing "no predicate" with the seekable-cursor-vs-residual distinction already written correctly elsewhere: - handler: the "real bound on work" claim, the short-page rationale - SearchFieldValuesQueryShapeTests: "ANY predicate" + "reads exactly n index entries", and added what the test can and cannot pin (a SQL string, not a plan / visibility work / payload I/O) - GetSearchFieldValuesHandlerTests: "no gap between what the engine looks at and what it hands back", and the current-behaviour comment - record title, rule:, attempt-5 table row; api-conventions - regenerated docs/decisions/README.md so catalog and record agree again Tenth item, the same overclaim one level down and it survived the first retraction: the row bound was said to cap what the process holds in memory. It does not — payload width is unrestricted and one JSON array can contain arbitrarily many strings, each of which may enter the in-memory distinct set. It caps logical rows returned/materialized and round-trip count, nothing about bytes. Added as a third struck-through bullet next to the other two retractions.	2026-07-27 03:10:36 +02:00
timothy	5f73cd4482	docs(578): scope the bound to LOGICAL ROWS — physical work is not bounded, and I claimed it was ... Comment- and docs-only. Verified: the diff for both .cs files contains no non-comment line. HIGH (claim). "LIMIT n reads exactly n index entries and n rows" is false, and the bounded-physical- work reading it implied is false with it. Two mechanisms, both retracted explicitly in the record rather than quietly reworded: - MySQL purge lag. Deleted clustered-index records survive until purge runs and a range scan still traverses them, so returning 2,000 VISIBLE rows can touch far more index records. Deletion history therefore STILL affects physical work — precisely what attempt 4's failure was supposed to have made irrelevant. Attempt 5 removes the LOGICAL dependence on Id distribution; it does not make physical work independent of deletion history. - Unbounded row width. Artists/AlbumArtists are unrestricted TEXT/longtext and both SQLite and InnoDB spill to overflow pages, so a row count implies neither a byte count nor a page-read count. The guarantee is now stated as exactly what it is: at most 20,000 LOGICAL rows returned/materialized, and at most 10 round trips (11 for artist). The 392 KiB measurement is labelled one data point on one library whose credits average ~20 B/row, with an instruction to re-measure rather than extrapolate for long credit lists or MySQL over a network. Also noted: the query-shape test pins the SQL STRING — it cannot pin a plan, MVCC visibility work or payload I/O, and on MySQL using the index to satisfy ORDER BY is an optimizer choice, not a semantic guarantee. Precision fix, and the reviewer is right that the sloppy version misleads: "any predicate defeats LIMIT" is wrong, since the query's own cursor is a predicate. The distinction is a SEEKABLE PREDICATE ON THE ORDERING KEY (positions the scan, never discards a row) versus a RESIDUAL predicate (discards rows the engine already produced, so LIMIT bounds survivors and says nothing about how many were produced). Restated in the handler, the record and api-conventions. MEDIUM. docs/decisions.md still advertised "a superset LIKE pre-filter that may over-match but never under-match" for list-valued columns. That is the documented entry point for convention lookups, so a maintainer starting there was told to preserve exactly what round 4 deleted, in direct contradiction of the linked active record. Fixed. LOW. Two test comments read as current: "however many non-matching rows" (false past the ceiling — now bounded and cross-referenced to the test that pins that boundary) and the ampersand case "widens to the bare anchor" (no prefix predicate exists; kept because it is the input shape that broke the old scheme, now labelled as such). Fifth consecutive round of stale text, so this sweep was done by grepping the subject across handler, tests, record, decisions.md, api-conventions.md and the endpoint description: LIKE, ESCAPE, pre-filter, superset, over-match, under-match, anchor, keyspace, window, candidate, row cap, index entries, 392, and every deleted constant name. Every surviving hit is now either current-and-correct or explicitly framed as history.	2026-07-27 03:10:36 +02:00
timothy	373956fcee	fix(578): delete the SQL predicate — LIMIT only bounds work when there is nothing to discard ... BLOCKER. Attempt 4 bounded the Id KEYSPACE, and keyspace is not rows. Delete 20,000 historical rows, put one song at Id 20001, query artist?q=que: the walk burned all ten windows on empty ranges and returned [] for a table containing exactly one row. Capacity fell linearly with deletion ratio and no ratio was safe — one placed gap hides the next match. My record called that "heavily fragmented" and the endpoint description said loss happens "on a very large library"; the one-row example disproves both. Option A. The query now carries NO predicate at all — no LIKE, no LOWER, not even IS NOT NULL: SELECT Id, Artists AS Payload FROM SongMetadata WHERE Id > @AfterId ORDER BY Id LIMIT @Batch That is the whole fix, and it is the point. LIMIT truncates what survives a predicate, so with any predicate present it bounds the OUTPUT and says nothing about the WORK; the engine may evaluate and discard arbitrarily many rows first. Stripped to a bare primary-key range, LIMIT n reads exactly n index entries and n rows — independent of sparsity, deletion history or where the gaps fall. All selectivity moves into memory. A short page can now only mean exhaustion, which is precisely what it could not mean while a predicate was present. Four attempts, four wrong quantities: the result (a fixed budget the over-matching pre-filter starved), candidates returned (a no-match query must evaluate every eligible row before returning an empty page), keyspace width (above), and finally actual rows. The record carries the table; it is worth more than the code. Deleting the predicate deletes a whole bug family with it: the JSON-escape reasoning, the narrow-only-on-verbatim-ASCII rule, the exhaustive Unicode sweep that proved it sound, the ESCAPE '/' portability workaround, and the may-over-match-never-under-match invariant that turned out to be conditional on something untrue. SearchFieldValuesPrefilterSupersetTests is deleted entirely; the one assertion worth keeping — that the SQL has no predicate — moved to the query-shape suite, which pins the SQL string exactly so "just a cheap filter" fails a test instead of silently unbounding the walk. Measured cost of no server-side narrowing, on a seeded 20,000-song library (in-memory SQLite): worst case (no match, full walk) 20,000 rows / 10 round trips / 391.9 KiB / 119ms SQL, ~40ms warm end-to-end. Empty q, dense and non-ASCII prefixes all stop on page 1 at ~39 KiB and ~40ms. Judged acceptable for a debounced typeahead against a local file. If it ever is not, the answer is #669, not reintroducing selectivity — the record says so explicitly. Also fixed: - Round-trip count was advertised as 10; it is at most 10 for album_artist and 11 for artist, which also runs its EF query. The MAX(Id) probe is gone with the keyspace scheme, so there is no extra scalar call. - The duplicated-formula ceiling test is deleted rather than rewritten. It re-implemented the loop's arithmetic and would have passed through an off-by-one or a stall in the real loop; the dense integration tests carry that coverage. Its MaxVisited >= Window assertion was a style constraint in correctness clothing. - Stale text swept by grepping the mechanism nouns rather than re-reading: candidate/keyspace/ pre-filter/superset/row cap/LIKE/ESCAPE and the removed constant names, across handler, tests, record, api-conventions and the endpoint description. The two surviving "pre-filter" mentions are deliberate history. Test comments that rendered escaped non-ASCII as literal characters (which contradicted the raw-storage assertion in the same file) now show the escape text. New test List_Valued_Walk_Reads_Live_Rows_Regardless_Of_Id_Density reproduces the one-row killer and fails against attempt 4.	2026-07-27 03:10:36 +02:00
timothy	a37847e509	fix(578): a fixed row budget turns an over-matching prefilter into a false negative ... BLOCKER 1. The invariant a883e5f0 established — "the pre-filter may over-match, it must never under-match" — is only sound while the candidate set is not truncated. It was truncated. A non-ASCII or JSON-escaped prefix collapses the pattern to the bare `%"%` anchor, so every row becomes a candidate, and `ORDER BY Id LIMIT 1000` then spent the whole budget on rows that could not match. Seed 1000 songs by "zzz", put the only "éclair" in row 1001, ask for album_artist?q=é: a883e5f0 returns [], while 1b78dc9e returned "éclair" because its (separately broken) tighter pattern kept the candidate set small. Neither revision was correct — the old one under-matched at the pattern, the new one under-matched at the cap. Widening a predicate under a fixed budget starves it. So the budget is gone. Candidate rows are now walked keyset-paged on Id (`Id > @AfterId … ORDER BY Id LIMIT @Batch`), continuing past non-matching candidates and stopping on the first of: enough distinct exact matches for `limit`, a short page (source exhausted), or a 20,000-candidate-row ceiling in 2,000-row batches. The bound is on effort; it no longer silently decides the result, and the lossy case needs 20,000 rows that already passed the pre-filter before it bites. BLOCKER 2. The endpoint description and the record's rule claimed ordinal matching/dedup/ordering endpoint-wide. False for EF-backed fields: the database runs LOWER/DISTINCT/ORDER BY/LIMIT before any ordinal code, so `genre?q=é` still misses a stored "Éclair" on SQLite. Both are now scoped to the final in-memory stages, and the underlying gap is referenced as #668 rather than described as fixed. #669 (normalized SongArtist table) is referenced as the follow-up for the scan cost. Accuracy corrections to my own claims, all verified by re-running the mutations: - Only THREE of the nine Unicode cases fail 1b78dc9e (é/édith/BJÖRK — where query and stored casing differ, so the escape texts diverge); the other six pass it. The comment said all nine. They stay as continuity coverage, now labelled as such rather than as regression guards. - Ordering_Is_Best_Effort used "Zulu"/"Éclair", where DB and ordinal orderings BOTH pick "Zulu" — it could not demonstrate the divergence it claimed. Now "Zulu"/"apple", which actually diverges: ordinal ranks "Zulu" first, the DB ranks "apple" first, and limit=1 returns ["apple"]. The record sentence was false and is corrected. - The record printed literal "Édith"/"é" where it needed to show the escape TEXT (Édith, é), contradicting the very explanation it was giving. - Corrected the cost claim: the leading wildcard forces scan ACCESS, but each page stops once it has filled @Batch, so a dense query finishes early — it is not necessarily a full table scan. - The Unicode sweep is labelled a PROOF OBLIGATION: it is revision-independent and passes every revision, which is correct for what it is but must not read as regression coverage. One process note: the new record's frontmatter had a lone apostrophe inside a single-quoted YAML scalar ("SQLite's"). decisions_validate.py's hand parser accepted it; scripts/tests caught it.	2026-07-27 03:10:35 +02:00
timothy	1641ca8305	fix(578): the LIKE prefilter under-matched every accented artist; make the superset provable ... Review of 1b78dc9e found the pre-filter's correctness claim was false, and the claim was in the decision record as well as the code. F1 (high). The pattern JSON-encoded the whole query prefix on the reasoning that the stored text escapes non-ASCII, so encoding the prefix the same way would line up. It does not: SQL LOWER() lowercases the *escape text* (`É` -> `é`); it cannot case-fold the codepoint that escape denotes. So `q=é` built `%"é%`, the stored `Édith Piaf` never matched, and the row was discarded before the in-memory filter could accept it. Every accented artist — Beyoncé, Björk, Sigur Rós, Édith Piaf — was silently unsuggestable, which in a music library is the common case. The invariant that was missing, now stated in the code: the SQL pre-filter is an OPTIMIZATION. It may over-match; it must never under-match. Correctness lives in the in-memory filter. So the pattern now narrows only on the leading run of characters the JSON writer stores verbatim and stops at the first character it cannot prove — `q=Beyoncé` still narrows on `beyonc`, `q=é` narrows on nothing and leans on the row cap. Soundness rests on two facts now asserted by exhaustive computation rather than argued: no non-ASCII codepoint in U+0080..U+10FFFF OrdinalIgnoreCase-equals a printable ASCII character (false for InvariantCultureIgnoreCase, which folds ~190 — the choice of Ordinal is load-bearing), and the exact set of ASCII the encoder escapes. F1b. `UseRequestLocalization` honours Accept-Language, so the culture was caller-controlled and `ToLower()` plus the default linguistic `StartsWith(string)` let a header change the answer. Comparison is now OrdinalIgnoreCase and ordering StringComparer.Ordinal throughout — including the shared FilterSortTake that state/video_dynamic_range/content_rating also use. Sets unchanged, order now ordinal rather than culture-dependent. F2. The merge comment asserted an exactness the code does not have: sources truncate by their own ordering (DB collation / primary key), not the merge's, so a dropped value can outrank a survivor. Comment and record now say best-effort, exact only below the truncation points. F3/F4. The cap now rides `ORDER BY Id` rather than the JSON column: MySQL sorts TEXT by only max_sort_length bytes, so the old ordering was not deterministic there, and sorting the whole matching set was avoidable work. What the cap still does NOT bound is the scan — a leading-wildcard LIKE cannot seek an index — so that cost is now documented as accepted, with a normalized `SongArtist` table named as the follow-up candidate rather than left implicit. Every clause above is covered by a test verified to FAIL when that clause is mutated (old pattern builder: 5 red; culture chain: 3 red; cap=3 / cap=limit / ORDER BY json / no cap: red each). F5. Converted to a proper supersession. The old record did not merely hold a stale fact — it recorded song/music-video credits as an "intentionally-uncovered gap" and album_artist as unsupported, and this reverses that call, which `docs.decision-lifecycle` says is never a line-edit. `api.search-field-values` is archived with its original prose restored, and `api.search-field-values-sources` replaces it carrying the whole endpoint contract.	2026-07-27 03:10:35 +02:00
timothy	cd6f36185c	feat(578): artist typeahead covers music-video and song credits; album_artist stops 404ing ... `GET /api/v1/search/fields/{name}/values` sourced `artist` from `ArtistMetadata.Title` only — entity artists — so the free-text credits that `LuceneSearchIndex` also writes to the `artist` field (`MusicVideoArtist.Name`, `SongMetadata.Artists`) produced no suggestions, and `album_artist` 404'd outright. `MusicVideoArtist` turned out to be a real entity table, so it just joins the existing server-side pipeline as a `Concat` — one bounded `UNION ALL` + `LOWER(...) LIKE ... LIMIT` on both providers. `SongMetadata.Artists`/`AlbumArtists` are the hard case: EF 9 maps them as primitive collections (one JSON array per row in a single column), and neither provider can project the elements server-side — SQLite needs the SQL APPLY operator it lacks, Pomelo MySQL 9.0.0 has no primitive-collection support at all. Both failures are now pinned by a test, so a provider upgrade that fixes them shows up as a red rather than as a stale workaround. For those columns the handler pre-filters on the raw JSON (`LOWER(col) LIKE '%"<encoded-prefix>%' ESCAPE '/'` — a deliberate superset, since it matches a row and not an element), caps the rows at 1000 with an `ORDER BY` that makes the truncation deterministic, then splits and exact-filters in memory. Provider portability is by construction rather than by trusting `LIKE`: the prefix is JSON-encoded before matching (which is how it is stored, and which makes the pattern pure ASCII, so SQLite's ASCII-only `lower()` and MySQL's Unicode-aware `LOWER()` agree) and lowercased in C#, so the match is correct under a case-sensitive MySQL collation as well as a case-insensitive one. The escape character is `/`, never `\`: `ESCAPE '\'` is not a portable SQL literal. An empty `q` stays supported for these fields — the row cap already bounds it, and a non-empty-`q` carve-out would make one group of fields behave differently for the same client code. Docs: new `api.search-field-values-list-columns` record (additive sibling — the base record's rule still reads true; only its body's "intentionally-uncovered gap" claim was stale), plus `api-conventions.md`, `spa-conventions.md` §12 and the regenerated `v1.json`. Decisions-Edit: yes	2026-07-27 03:10:35 +02:00
timothy	214fad2dcd	fix(633): document the 0-based paging contract on the OpenAPI parameters ... `api.paging-zero-based` says `pageNum` is 0-based across `/api/v1` and every wrapper of it. That was true of the MCP tool catalog and the docs, and not true of the generated OpenAPI document: all 24 paging parameters across the 12 paged operations were emitted with no `description` at all, so a consumer reading only `v1.json` — the intended contract, and what generated clients surface to their users — had to infer the base from `default: 0`. That is the same inference that cost #487 a verification pass on the MCP side, where the description was present but wrong. Annotates each `[FromQuery]` paging parameter with `[Description]` (`System.ComponentModel`), the mechanism `parentId` already used in ImagesController, and regenerates `v1.json`. `pageSize` states the endpoint's OWN cap, because the caps genuinely differ — 100 typical, 200 auto-tune members, 1000 search/all-items — and the record forbids documenting one global number; it also states that the offset derives from the effective (capped) size, so an over-large `pageSize` narrows the page instead of widening the offset. The generated TypeScript client covers DTOs only, not query parameters, so it is unchanged; `endpoint-index.md` carries summaries, not parameter descriptions, so it is unchanged too. Pinned by OpenApiPagingContractTests against the in-process generated document. The test NAMES the expected set of 12 paged operations rather than only filtering for parameters called `pageNum`: a filter cannot see an endpoint that should page and doesn't, which is exactly how two MCP tools escaped the equivalent check in #616. Set equality is asserted in both directions, and the caps are pinned per endpoint so a description naming the wrong cap fails — a wrong justification outlives a wrong line. Mutation-verified both ways: dropping one `[Description]` reddens the description test, and making one endpoint stop exposing `pageNum`/`pageSize` under those names reddens the set-equality test. Refs #633 Decisions-Edit: yes	2026-07-26 11:10:22 +02:00
timothyandClaude Opus 5	8d35a2792f	fix(616): document paging as 0-based, expose channelId on playout detail ... #616 filed three MCP/API paging traps. Two were real; one was not, and one was already half-fixed on main. Verified each against the code before changing it. REAL — pageNum documented as 1-based. `ToolCatalog.Page()` described pageNum as "1-based page number" while every paged controller defaults it to 0, floors it with `Math.Max(0, pageNum)`, and skips `PageNum * PageSize`. A caller that trusted the description started at page 1 and silently lost the first page: no error, just a short set that reads as data loss rather than an off-by-one (it cost #487 a verification pass). Fixed in the description rather than by making the MCP layer 1-based: /api/v1 is additive-only post-freeze, 0-based is load-bearing in a dozen controllers and the SPA, and a 1-based wrapper over a 0-based API would make the same parameter name mean two different things on two surfaces a reader reads together. NOT REAL — "pageSize caps the page but the offset honors the requested value". Not reproducible on any endpoint. Every controller clamps before passing, every handler skips by the clamped size, and GetCollectionItemsHandler re-clamps defensively. The reported observation (pageSize=500&pageNum=2 on a 204-item collection returning 4 items) is exactly correct 0-based behaviour at the clamped width of 100 — page 2 is items 201-204. The issue's own trap-1 table states this. Pinned by test rather than "fixed". ALREADY FIXED — playout LIST rows gained channelId in #297 (2026-07-22), three days before #616 was filed; the report was measured against prod, which runs an older :prod image. The DETAIL response (PlayoutResponseModel) genuinely still lacked it, so channelId is added there (additive) and the reset_channel_playout argument now names the trap: the id spaces overlap numerically, so passing a playout id silently resets a different channel and returns a plausible 202. Tests, both mutation-verified (each fails when its fix is reverted): - ToolCatalogTests pins "0-based" on EVERY paged tool's pageNum description, with a non-empty guard so it can't pass vacuously over an empty tool set. - GetCollectionItemsHandlerTests pins 0-based page boundaries and proves the offset derives from the clamped pageSize (page 1 at pageSize=500 returns items 101-150; the mutation that honors 500 returns an empty page). Docs: new decision record api.paging-zero-based (catalog regenerated), the api-conventions paging bullet, and a Paging section in docs/mcp.md. OpenAPI v1.json + web/src/api/generated/v1.d.ts regenerated for the added field. fixes #616 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:16:00 +02:00
timothyandtimothy	65c0e09179	feat(415): per-channel fault detection — server-derived health object + Problems filter (#581) ... Closes #415. Server-derived health object on the channel list + detail DTOs (built-timeline detection, kind-agnostic across all 5 PlayoutScheduleKind; assessable gate keyed to the owning channel's mode), single "Problems" SPA filter with per-fault badges. Supersedes #72's api.channel-health-signal decision. Co-authored-by: Timothy <timothy.look@gmail.com> Co-committed-by: Timothy <timothy.look@gmail.com>	2026-07-23 20:45:19 +00:00
timothyandClaude Opus 4.8	9cb51f6a73	docs(434): [decisions-edit] update field-values decision + api-conventions for DB sourcing ... Edits the api.search-field-values decision record's rationale prose in place (same key, same date, not a reversal) to describe the DB-sourced per-field distinct-values design and the narrowed allow-list, replacing the superseded Lucene-term-dictionary description. Updates the endpoint's api-conventions.md entry the same way. Regenerated docs/decisions/README.md via build_decisions_catalog.py; decisions_validate.py passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-23 20:44:15 +02:00
timothyandClaude Opus 4.8	c2fb62dc88	docs(434,435,438): decisions records, spa-conventions §12, api-conventions ... Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-23 20:44:15 +02:00
timothy	7757814766	feat(74): channel graphicsElementIds + graphics builtIn; regen OpenAPI	2026-07-22 22:11:46 +02:00
timothy	f1de436ca7	feat(60): expose channel preview capability on GET /api/v1/channels	2026-07-21 23:13:08 +02:00
timothyandClaude Opus 4.8	928784ba48	fix(135): from-lineup advanced overrides can express "clear to none" ... CreateChannelFromLineupHandler resolved every advanced override with advanced.X ?? template.X, so null always meant INHERIT and a channel could not drop a template-set watermark / filler / preferred language. Add an optional typed `clear` enum list to CreateChannelFromLineupAdvancedOptions: omitted/null still inherits (byte-stable for existing clients), a field named in `clear` is forced to none. Set+clear of the same field is a 422. The enum (CreateChannelFromLineupClearField) lives in ErsatzTV.Core so the OpenAPI string-enum scan renders it as a string enum, matching every sibling advanced-options enum. Handler resolves clearable fields once via ResolveClearable and validates set/clear conflicts via ValidateClear; reference validation skips existence checks for cleared (null) refs. SPA: the shared advancedOptions model re-adds a real "None" option to the five id selects (watermark + fillers) in both the Channel Builder and the Auto-Tune DetailPanel, routed through a CLEAR overrides sentinel that applyOverridesToRequest folds into advanced.clear (never leaking onto the wire as a field value). The backend enum also covers the preferred audio/subtitle language strings for machine clients; the SPA text inputs keep "empty = inherit" (tri-state deferred). Docs: api-conventions.md §2, spa-conventions.md §11, decisions.md record api.from-lineup-clear-to-none; v1.json + generated TS regenerated. fixes #135 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-21 22:25:58 +02:00
timothy	aa76994825	docs(525): correct logo-download rejection status to 422, not 400 ... Live-E2E of the write path (scripts/e2e-local.sh) confirmed the feature end to end — good URL -> cached /iptv/logos/<hash>, M3U emits the cached URL, cached logo serves back as PNG, rejected save leaves the prior logo intact — and caught that a bad/non-image/oversized logo rejects as 422 (BaseError -> ValidationProblemDetails via ToErrorResult), not 400. 400 remains model-binding-only. Corrected channels.md, api-conventions.md, and the graphics.channel-logo-caching decision Rule + catalog.	2026-07-21 13:19:07 +02:00
timothy	56a18cd5dc	docs(525): record download-on-save decision; update channels + api-conventions ... New lifecycle record graphics.channel-logo-caching (supersedes: none — narrows for YAML image elements). Regenerated the active catalog. channels.md + api- conventions.md updated for the new save-time download + 400s.	2026-07-21 13:18:48 +02:00
timothy	bb7f57d04d	docs(67): record the shared-preset decision, watermark seeding, and the additive DTO field	2026-07-20 20:48:14 +02:00
timothyandClaude Opus 4.8	be25df670e	feat(431): TTL-cache health-check results; ?refresh=true forces a fresh run ... GET /api/v1/health re-ran all 14 health checks on every request, 4 of which shell out to ffmpeg/ffprobe via CliWrap — so each poll spawned ~4 subprocesses. The existing HealthCheckSummary cache was write-only. Cache the full result list for 30s inside HealthCheckService keyed on a new "healthcheck.results" entry; a non-forced call returns it on a hit, skipping the checks and the (subscriber-less) summary publish. Add a `bool forceRefresh` first parameter to IHealthCheckService.PerformHealthChecks: the API poll path reads the cache, while startup (RunHealthChecksService) and the troubleshooting support bundle force a fresh run. Refresh surface: GET /api/v1/health gains an optional `[FromQuery] bool refresh` (additive, follows the ?deep= exemplar); the SPA "Refresh health" button calls /api/v1/health?refresh=true, the initial/poll load does not. Tests: HealthCheckService cache-hit vs force-bypass (mutually opposing, non-vacuous), handler+controller refresh-flag threading, SPA refresh URL. Docs: decisions.md 2026-07-19 (#431), api-conventions §2; regenerated v1.json. fixes #431 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-19 14:41:12 +02:00
timothyandClaude Opus 4.8	1aa1f0cf5b	fix(464): render real channel logos in guide grid + channels list ... The guide/EPG grid (/app/guide) and the channels list (/app/channels) always drew the generated initials "bug" because the browse DTOs never carried a logo URL — GuideScreen/ChannelsScreen rendered <ChannelLogo> with no src. The logo data existed (it round-trips through the channel editor) but never reached these views. Add a rooted, directly-usable Logo URL to ChannelGuideChannelResponseModel and ChannelResponseModel, populated by a single Channels.Mapper.GetLogoUrl helper (#181 artwork convention): /iptv/logos/{file} for an uploaded logo, the absolute URL passed through for an external one, null when unset so the SPA keeps its generated-initials fallback. The guide query now includes Channel.Artwork. Regenerated OpenAPI + v1.d.ts; updated api-conventions.md + domain-model.md. fixes #464 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-19 13:28:00 +02:00
timothy	551366aa72	Merge pull request 'feat(293): paginate GET /api/v1/search/all-items to cap DoS exposure' (#442) from feat/293-search-allitems-cap into main	2026-07-18 12:17:20 +00:00
timothyandClaude Opus 4.8	c57fbf9826	docs(293): note the pageNum upper clamp (MaxAllItemsPageNum) in the decision + api-conventions ... Fix delta re-review flagged the decision entry + §5 note still described the pre-fix pageNum = Math.Max(0, pageNum); the shipped code clamps the upper bound too (0..2_000_000) to stop pageNum*pageSize overflowing int to a 500. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 13:40:20 +02:00
timothyandClaude Opus 4.8	ac7965dee4	feat(293): paginate GET /api/v1/search/all-items to cap DoS exposure ... The all-items endpoint fired ten index searches with limit:0 (every hit), so a broad authenticated query materialized the whole index into one response. Add optional pageNum/pageSize (clamped 1..1000; pageNum 0..2_000_000 so skip can't overflow int) and an additive per-kind Totals on the response; the SPA add-all flow now pages to completeness instead of a single unbounded fetch. - SearchController.SearchAllItems: clamp params (Logs §1 precedent), map Totals - QuerySearchIndexAllItemsHandler: skip=pageNum*pageSize, limit=pageSize, read SearchResult.TotalCount per kind - SearchResultAllItemsResponseModel: additive Totals (frozen-v1-safe) - web/src/api/search.ts: getSearchAllItems paging params + getAllSearchItemIds (pages until each kind hits its total; empty-page safety break) - tests: controller clamp/thread/totals, handler skip/limit/totals, SPA paging - docs: decisions.md 2026-07-18 (#293), api-conventions.md §5; regenerated OpenAPI Design: issue option (a) full pagination, operator-confirmed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 13:09:06 +02:00
timothyandClaude Opus 4.8	2281f2e764	fix(308): idempotent concurrent Add*ToCollection instead of a composite-PK 500 ... Two concurrent adds of the same item both membership-check it absent, both insert the CollectionItem composite key, and the loser's SaveChangesForcingVersion threw an uncaught DbUpdateException (SQLite 19 / MySQL 1062) -> 500. Now the loser is an idempotent no-op. - ConcurrencyExtensions.TrySaveChangesForcingVersion: bool-returning sibling that catches only a classified unique/PK violation and returns false. - 10 single-item Add*ToCollection handlers: return Unit.Default (no-op, skip fan-out) on false — the racing winner already inserted + rotated + rebuilt. - Bulk AddItemsToCollection: retry on a fresh context against recomputed membership so a partial-overlap collision doesn't drop the non-colliding items (bounded loop; common no-collision path runs once). - Provider detection via a TvContext.IsUniqueConstraintViolation static delegate (matches the existing IsSqlite/LastInsertedRowId provider seam), wired from Startup to SqliteErrorClassifier / MySqlErrorClassifier. - Add*ToPlaylist is NOT affected (PlaylistItem has its own identity PK; a playlist may legitimately contain the same item more than once). Tests: a negative-control anchor proves the race genuinely throws a classified exception; end-to-end handler tests reproduce a real cross-connection race via a shared-cache SQLite harness + a SavingChanges interceptor (the single-conn in-memory fixture cannot). Every fix-dependent test verified to fail with the catch disabled. Docs: api-conventions.md §7a (idempotent insert under concurrency) + decisions/optimistic-concurrency.md. fixes #308 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 13:02:14 +02:00
timothyandClaude Opus 4.8	e364b338e6	feat(425): per-source rotation weights + query corrections for auto-tune channels ... Auto-tune channels can now carry per-content-source rotation weights (weighted round-robin, e.g. 3x Show A / 1x Show B) and query corrections (exclude / add-untagged), supplied at bulk-create time via an optional `sources: [{sourceId, weight, excluded}]` on each AutoTunedChannelRequest. Design (Option A, reuse #70): when a source is customized the channel is backed by a system-owned MultiCollection of per-source SmartCollections carrying the weights, with PlaybackOrder.WeightedShuffle -- the exact path WeightedShuffleCollectionEnumerator already consumes. All-default weights keep the #69 single-SmartCollection fair-share shape. - Discriminators: TV -> live show_title:"X" (episodes carry no parent-show id in the index); movies -> stable id:{mediaItemId}. - Materialization is axis-dependent: TV materializes every base show individually (un-weighted shows keep per-show fair-share) + a live remainder at weight 1; MovieGenre materializes only touched movies + one count-weighted remainder. - Remainder = (base) AND NOT (materialized union excluded) -- a partition. - New nullable OwnedByChannelId on SmartCollection + MultiCollection (dual-provider migration); owned rows are hidden from the collection lists and cascade-cleaned on channel delete. Tests: AutoTuneAxisMap query/partition units; DB-backed weighted-path handler tests (TV materialize-all, movie count-remainder, exclusion, no-customization fallback); delete-cleanup. Docs: decisions.md, domain-model.md, api-conventions.md; OpenAPI trio regenerated. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 03:52:06 +02:00
timothy	ae22107d98	feat(176): GET /api/v1/search/fields endpoint + regenerated api artifacts	2026-07-18 02:41:50 +02:00
timothyandClaude Opus 4.8	ed6c43065f	feat(164): guided remediation for health checks (server-declared {Kind, Target}) ... Make the ~14 health checks actionable: each check that has a fix now declares where to go, and the SPA acts on it. Backend: - Widen domain HealthCheckLink (string Link) -> (string Target, HealthCheckLinkKind Kind) with ExternalDoc|AppRoute + factories; only the 4 link-building checks and the API mapper touched .Link. - Evolve HealthCheckResponseModel additively (/api/v1 frozen-additive): keep deprecated string? Link (still populated), add Brief (the BriefMessage the mapper was silently dropping) and nested Remediation {Kind, Target}. Kind is a mapped string, not a wire enum. - Make Mapper.GetStatus total: NotApplicable no longer throws (defensive; handler still filters it). InternalsVisibleTo(ErsatzTV.Tests) added to unit-test totality. - Fix 2 stale Blazor route links (media/trash -> /app/trash, search?query -> /app/search); add AppRoute remediation to actionable checks that had none (libraries / schedules / ffmpeg-profiles / settings). SPA: - DashboardScreen health panel renders remediation: AppRoute -> client-side nav button, ExternalDoc -> new-tab anchor; detail text truncates with title-hover. - Remove the dead "Open Classic UI" -> /system/health row from SettingsScreen (a #91b leftover that just 302'd to /app); update its regression test. Docs: decisions.md (#164), api-conventions.md (deprecate-in-place DTO evolution), blazor-route-parity.md (Section 4 correction); v1.json/v1.d.ts/endpoint-index regenerated. fixes #164 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 00:51:40 +02:00
timothyandClaude Opus 4.8	8f61ad6530	feat(385): per-channel overrides in auto-tune bulk-create ... Auto-Tune DetailPanel backend (#385), additive half. The create request `AutoTunedChannelRequest` gains three optional per-channel fields, all backward-compatible (omit = PR1 behavior): - `templateId` — overrides the batch template per channel - `advanced` — reuses the manual Channel Builder's `CreateChannelFromLineupAdvancedOptionsRequest` verbatim (24-field override set, `advanced.X ?? template.X` stamp contract). Axis default fills `PlaybackOrder` only when the caller leaves it null. - `logo` — uploaded channel image, `Sanitized()` at the request boundary (#283 stored-XSS defense), forwarded to `CreateChannelFromLineup.Logo` Resolved per channel inside `CreateAutoTunedChannelsHandler.CreateOne`, so one channel's bad override still yields a per-channel Failed/Skipped without aborting the batch. Per-source rotation weights + query corrections are split out to #425 (they need a MultiCollection-of-per-source-SmartCollections redesign — #70's WeightedShuffle reads weights only off MultiCollection join rows, and an auto-tuned channel is one SmartCollection). Bug-initials/colour generated logo also deferred (needs persisted Channel state + FFmpeg-pipeline wiring). Tests: handler override-threading (per-channel wins, axis default preserved, no-override baseline) + request `ToCommand()` logo sanitization. OpenAPI trio regenerated. Docs: decisions.md, api-conventions.md, domain-model.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-17 23:33:10 +02:00
timothyandClaude Opus 4.8	0009607a09	feat(384): auto-tune DetailPanel content-source member read endpoint ... GET /api/v1/channels/auto-tune/members lists the distinct content sources a proposed auto-tune channel's server-generated SmartCollection resolves to — parent shows for the TV axes (ItemCount = query-matching episodes), movies for the movie-genre axis — reusing the existing PagedLibraryBrowseItemsResponseModel (no new schema). The handler runs the server-owned AutoTuneAxisMap.GenerateQuery through ISearchIndex (client never sends Lucene, per #69 PR1) and rolls matching leaf items up to their distinct sources, mirroring GetSmartCollectionItems so the DetailPanel preview matches what the built playout will contain. Backend child of #383 (Auto-Tune DetailPanel milestone); read-only, cold review acceptable. Handler + controller tests (9 new). OpenAPI + endpoint-index regenerated; d.ts unchanged (reuses existing schema). Docs: api-conventions §5, decisions.md 2026-07-17, domain-model. fixes #384 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-17 09:40:44 +02:00
timothy	0320735f47	docs(69): auto-tune OpenAPI regen + api/domain/decisions docs ... Refs #69	2026-07-16 22:18:52 +02:00
timothyandOpenAI Codex	489956b167	fix(api): protect local library path details ... Fixes #334 Co-Authored-By: OpenAI Codex <codex@openai.com>	2026-07-16 18:49:03 +02:00
timothyandClaude Opus 4.8	216130b4d7	fix(#172): API hardening — null-name 500s, duplicate template items, unreachable 404 ... Clears the still-live findings from #172 (verified against main; #2/#4/#7 and the auth/search/Trakt tail were already deliberate-documented or fixed since 2026-07-07). - Null/empty Name → 500 (10 create/replace handlers). Block/Template/DecoTemplate/Deco Create+Replace/Update + UpdateFFmpegProfile did `request.Name.Length > 50` on a client-nullable string → unhandled NullReferenceException → HTTP 500 (no global exception filter). Now `string.IsNullOrWhiteSpace(request.Name) || .Length > 50` → 422; also rejects empty/whitespace names, matching the group-create handlers' NotEmpty behavior. CreatePlaylist coalesces null→"" at the DTO so it was an empty-name persist, not a 500; guarded the same way. - ReplaceTemplateItems overlap validation iterated with an `item == otherItem` record value-equality skip, so two exact-duplicate items were value-equal and bypassed the intersection check (both persisted). Now index-based (i != j) so duplicates register as a self-intersection and are rejected 422. - Trimmed the unreachable 404 ProducesResponseType from POST /api/blocks/groups and POST /api/templates/groups (a create has no parent lookup that can 404); v1.json regenerated. - Regression tests: all 10 name-guard paths + the duplicate-items path (19 cases). - Docs: decisions.md entry + api-conventions.md §3b null-safe-validation bullet. fixes #172 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-13 01:16:52 +02:00
timothyandClaude Opus 4.8	ef2bd65c27	feat(api): #286 — mount the whole /api surface at /api/v1 ... Version every /api route to /api/v1 (251 controller routes + ~24 Location headers + the scanner callback URL + the Startup request-log literal), uniform across the machine API, auth, scanner and scripted-build surfaces. Add ApiVersionRewriteMiddleware: a legacy unversioned /api/* request is rewritten (NOT redirected) to /api/v1/* in-pipeline — method, body, auth headers and query survive — carrying RFC 8594 Deprecation/Sunset headers, so curl / the future MCP server / bookmarks keep working. An already- versioned path passes through; a future /api/v2 is never forced to v1. Standardize the route convention (leading-slash absolute route per method, no class-[Route] — except the two Scanner/Scripted controllers whose ~all actions share a parametrized {id} prefix), enforced by ApiRouteVersioningTests (^/api/v\d+/ over the whole Controllers.Api surface; browser-nav /auth/oidc/login is out of scope). Regenerate v1.json (160 paths, all /api/v1)/endpoint-index/v1.d.ts; sweep 945 SPA request literals + the test mocks (regex + positional URL parsers). /api/v1 is additive-only after freeze; the legacy-rewrite shim sunsets in ~2 releases (owner decision) with removal tracked as a Phase-3 follow-up. Docs: decisions.md 2026-07-13, api-conventions §1/§9, rest-api/spa-conventions/ blazor-route-parity/e2e-local/domain-model. fixes #286 refs #197 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-13 00:30:20 +02:00
timothyandClaude Opus 4.8	8090e10408	fix(api): #265 — If-Match evaluates per RFC 7232 (valid-but-non-matching → 412, not 400) ... The shared optimistic-concurrency parser (ConcurrencyHeaders.ParseIfMatch) classified any non-canonical/weak/list If-Match value as Malformed → 400. Per RFC 7232 §3.1 a syntactically -valid entity-tag that simply doesn't strong-match must be 412; 400 is only for a genuine grammar violation. - Rewrite ParseIfMatch as a real RFC 7232 entity-tag/list parser: walks the comma-separated 1#entity-tag list, validates each [W/]DQUOTE *etagc DQUOTE member, and collects the strong members whose opaque text is our canonical decimal. Weak / empty / non-canonical / out-of-range tags are valid but contribute no version (→ empty set → 412); genuine grammar violations (unquoted, SP-in-tag, unterminated, garbage) → 400. - Reshape IfMatchCondition.ExpectedVersion : Option<int> → ExpectedVersions : Option<Seq<int>> and VersionedAggregateExtensions.CheckVersion → set membership (any strong match proceeds; empty set always 412). Threads through 10 replace/update commands + handlers + request mappers + 9 controllers. - No wire-contract change (400 + 412 already declared on every PUT; the field is header-derived and internal — no DTO/route/response-type/OpenAPI change). - Tests: ConcurrencyHeadersTests rewritten for the new classification (lists, weak, empty, non-canonical → Version/empty-set; grammar violations → Malformed) + new VersionedAggregateExtensionsTests for CheckVersion membership/empty-set/force-write. - Docs: api-conventions.md §7a rewritten; decisions.md entry appended. Refs #253 #197 fixes #265 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 23:09:36 +02:00
timothyandClaude Opus 4.8	ec26e1be5b	fix(api): #316 review — POST-ify graphics-elements refresh, LockedError→409, no-store machine-key ... - GET /api/graphics-elements no longer side-effects; refresh moved to POST /api/graphics-elements/refresh (204), closing a CSRF vector on a GET. - PrepareTroubleshootingPlaybackHandler now returns a typed LockedError from both atomic lock-acquire failures; ApiResults.ToErrorResult maps it to 409 instead of falling through to 422, so a lock lost in the race between the controller's pre-check and the handler's atomic acquire still reports 409. - AuthController.MachineKey sets Cache-Control: no-store + Pragma: no-cache on the 200 response carrying the master API key. - Reworded the stale "subtitleId query parameter" endpoint description now that playback/start takes a JSON body. - Regenerated openapi/v1.json + docs/endpoint-index.md; docs/api-conventions.md updated with the LockedError pattern (§3a) and the ToErrorResult table row. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 21:50:42 +02:00
timothyandClaude Opus 4.8	461c763dc6	docs: #295 PR2 + #301 — decisions entry, api-conventions §9, e2e-local browser flow ... - decisions.md: new entry (SPA cookie-only cutover, boot-gate-not-route, #301 POST-ification rationale, machine-key-read + OIDC-logout residual) + TOC line. - api-conventions §9: #301 resolved (POST-ify) + 'never add a side-effecting GET' standing rule; machine-key endpoint added to the auth surface list; PR2-shipped note. - e2e-local: fix stale 'no key required' claim (fail-closed since #197) + browser setup/login boot-gate flow. (spa-conventions §5e rewrite landed with the SPA-consumers slice.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 21:50:42 +02:00
timothyandClaude Opus 4.8	7a9b30de71	fix(api): #269 review fixes — rebase force-write delta so rotation survives a race (Codex F1/F3) ... Independent Codex review (reconciled by Fable against a MERGEABLE fork verdict) found SaveChangesForcingVersion silently DROPPED a pending Version++ under a concurrent versioned-write race: on DbUpdateConcurrencyException it adopted the DB's current Version verbatim (original = current = dbVersion), so a bumping sibling committed at dbVersion instead of dbVersion+1. Net: an editor holding the concurrent writer's ETag was never invalidated by the sibling's change — the exact lost-update the #253/#269 contract exists to close, lost under the very condition the helper handles. F1 fix (shared helper, corrects all 25 bumpers incl. the pre-existing Add*ToPlaylist / schedule-item writers): rebase the pending delta on top of the stored token — pendingDelta = current - original; original = dbVersion; current = dbVersion + pendingDelta Bumpers (delta 1) advance to dbVersion+1; non-bumpers/deletes (delta 0, e.g. ErasePlayoutHistory) still adopt the stored token unchanged, so RootWriterForceVersionTests is unaffected. Idempotent across the bounded retry loop. F3: the force-race tests now assert Version==3 (rebase), not just membership survival; added the missing Playout force-race+rotate test. Negative-controlled: with the helper fix reverted, both strengthened tests go red. F2 (Medium, deferred → #308): two concurrent same-item Add*ToCollection can both pass the membership check and the loser 500s on the composite-PK violation (DbUpdateException, which the helper doesn't catch). Pre-existing and narrow (no corruption); doc claims softened to name it. Filed #308. Docs: api-conventions §7a + decisions.md prose corrected from "adopt the stored token" to the rebase semantics. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 19:40:32 +02:00
timothyandClaude Opus 4.8	83f753b211	fix(api): #269 rotate aggregate ETag on Collection/Playout config siblings ... Complete the #253 optimistic-concurrency contract's cross-editor ETag rotation tail. The non-If-Match config siblings mutated editor-visible state without bumping Version, so a concurrent editor of the same root never invalidated. Now the Collection Add*/Remove handlers bump Collection.Version, and UpdateCollection / UpdatePlayout / the three ScheduleFile writers (which already force-wrote past a concurrent bump) now bump too — all via SaveChangesForcingVersion (no If-Match → force write, never 412/500). No-op idempotence (Fable-caught trap): these gate reindex/BuildPlayout fan-out on SaveChanges()>0, so an unconditional bump would fire spurious rebuilds on an idempotent re-add / same-value re-submit. Each now short-circuits a genuine no-op before the bump — Add handlers by an explicit membership check (also fixing a latent duplicate-CollectionItem insert), scalar writers by ChangeTracker.HasChanges(). Corrects #269's framing: the Add*ToCollection family is not repository-mediated (IMediaCollectionRepository is read-only); each handler writes via its own dbContext, so the scanner's separate membership path is unaffected (a background scan does not rotate the editor ETag). Tests: CollectionEtagRotationTests + PlayoutScheduleFileEtagRotationTests (rotation, no-op-without-bump-or-rebuild, force-write-past-concurrent-bump), no-op guard proven non-vacuous by inverting the membership check. Docs: api-conventions §7a + decisions.md. No new status codes / no OpenAPI change (these endpoints take no If-Match, never 412). The #265 RFC-7232 If-Match parser refinement is a separate PR. fixes #269 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 19:40:32 +02:00
timothy	a81f024840	Merge remote-tracking branch 'origin/main' into ci/303-api-docs-blocking	2026-07-12 17:43:29 +02:00
timothy	c34d2bdbf2	Merge remote-tracking branch 'origin/main' into ci/303-api-docs-blocking ... # Conflicts: # docs/decisions.md	2026-07-12 17:34:48 +02:00
timothyandClaude Opus 4.8	aa2e13fa51	ci: #303 H4/H5 blocking api-docs gate — fail on stale OpenAPI artifacts ... Adds a blocking `api-docs` CI job: when a PR diff touches the API surface (ErsatzTV/Controllers/Api/** or ErsatzTV.Core/Api/**) it rebuilds the generated artifacts from source — v1.json, v1.d.ts, endpoint-index.md — and fails if any is stale in the diff. Mechanizes the "docs-update in the same PR" rule for the API contract (docs-reminder stays a non-blocking route-parity nudge). Path-gated INSIDE the job (per-step `if:` on a detect output), not via a top-level `if:`, so the check always reports a status on every PR and is safe as a required check: API-free PRs skip the dotnet/node setup + regen and pass trivially. Verified the gate reproduces the committed baseline: a fresh build regenerates v1.json byte-identical to HEAD (incl. all 244 auth security/401 blocks). The only footgun is local — update-openapi.sh runs dotnet-getdocument against the already-built assembly, so a stale bin/ emits a stale spec; api-conventions.md §5 now flags "build first". CI is immune (fresh checkout has no bin/). Docs: api-conventions.md §5 (two-place CI enforcement + stale-assembly note), decisions.md (new entry). Refs #303. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 17:18:09 +02:00
timothy	5a12aae66e	Merge remote-tracking branch 'origin/main' into fix/269-force-version-on-root-writers ... # Conflicts: # docs/decisions.md	2026-07-12 17:17:46 +02:00
timothyandClaude Opus 4.8	21b49e6a42	chore(#269): remove accidental web/node_modules symlink from PR ... Fix-commit re-review (cold fork) caught that e383c253 tracked a machine-specific absolute-path symlink `web/node_modules -> /Users/.../web/node_modules` (created for the eslint pre-push hook). It slipped past `.gitignore` because the `web/node_modules/` trailing-slash pattern matches only a directory, not a symlink; a real node_modules dir (a copy) would have been ignored. Untrack it and tighten the ignore to `web/node_modules` (matches symlink or dir) so it can't recur. Also tightens the §7a / decisions.md "they already catch" phrasing (LOW review nit): only BuildPlayoutHandler catches; PlayoutTimeShifter is insulated by running solely on the background worker, never the request path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 17:09:08 +02:00
timothyandClaude Opus 4.8	e383c253cc	fix(api): #269 review — force-write ErasePlayoutHistory + document boundaries ... Independent adversarial review (cold fork + Codex) of the first cut converged on one real miss and two boundaries to document. - **ErasePlayoutHistoryHandler** (HIGH, both reviewers): modifies Playout ROOT scalars (Seed/Anchor/OnDemandCheckpoint) *without* bumping Version, inside an explicit transaction with no try/catch, so it 500s on a concurrent bump — reachable via POST /api/playouts/{id}/erase-items-and-history. My first sweep filtered on "Version-bumpers + deletes"; the true exposure surface is "any handler leaving a versioned root Modified/Deleted", so this slipped through. Now routes through SaveChangesForcingVersion (+ a non-vacuous through-handler test that exercises the explicit-transaction path). Re-swept with the correct filter: ErasePlayoutItems (AsNoTracking + ExecuteDelete children only) and ResetAllPlayouts (read-only + enqueue) are NOT exposed. - **Background build/time-shift Playout-scalar writers** (BuildPlayout via PlayoutBuilder, PlayoutTimeShifter): token-guarded too, but intentionally left on plain save — they already catch (build-failure, not 500), and force-writing would persist output built from stale config (the concurrent config bump already enqueues a rebuild). Documented as a deliberate boundary, not a gap. - **Item-add index collision** under force-write: documented as an accepted Phase-1 effect (non-corrupting, self-correcting; reload-recompute refinement is a #197 candidate). Also corrects the docs' "every Version bumper" framing to the true filter and the test docstring's over-broad non-vacuity claim. Full ErsatzTV.Tests green (1483). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 16:59:01 +02:00
timothyandClaude Opus 4.8	e8c3481ea5	fix(api): #295 PR1 — fold in fix-commit re-review (2nd Codex round) ... Fix-commit re-review confirmed the 1st-round fixes resolved and caught a 2nd round: - HIGH — env-seed vs. setup race: an attacker could claim admin in the startup window before LocalAdminSeedService runs, and the seed's insert would then be swallowed (attacker credential persists, defeating env recovery). Fixed structurally: the setup-claim endpoint is CLOSED (409) whenever Auth:LocalAdmin:Password is configured — the env seed owns the credential, so there's no claim to race (also strengthens the setup-claim TOFU posture). Config.setupRequired reflects it. - LOW — a concurrent setup race-loser now returns 409 (not 422); ClaimLocalAdmin's DbUpdateException catch re-checks existence and rethrows genuine/transient DB errors instead of masking them as "already configured". - MEDIUM (accepted, documented) — two simultaneous authenticated password changes are a non-serializable lost-update; accepted for a single-admin system (self-healing via re-login, implausible timing). +3 AuthController tests (env-seed closes setup / setupRequired gating). Full ErsatzTV.Tests green (1506); no generated drift. Docs updated. Refs #295 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 16:52:23 +02:00