5 Commits

Include renames

Author	SHA1	Message	Date
timothyandClaude Opus 5	78ec997eae	docs(616): stop the record title and mcp.md from contradicting their own bodies ... Two LOWs from the re-review of af39123e. Both are the same defect I have already corrected twice on this branch: a universal claim that the corrected body right below it disproves. These read as normative, so a reader who stops at the title gets the false version. - The record was titled "...and every wrapper says so" while its own body admits the 12 OpenAPI pageNum parameters carry no description at all (tracked as #633). Retitled to state the target and name the exception. - docs/mcp.md led with "Rows that reference another entity carry that entity's id" — but PlayoutListItemResponseModel.ScheduleName ships with no schedule id. Restated as a rule about ACTIONABLE references, matching the wording the record already uses, with the known exception named. The two remaining LOWs are accepted deferrals, not fixed here: the >100 rerun collection truncation needs paging-to-completeness plus a multi-page fixture (#634), and the catalog test's forward-looking gap (it compares tool names, not PathTemplate against the paged-endpoint set) would need the MCP test project to reference the controllers to close properly. Docs only; catalog regenerated. No behaviour change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:51:14 +02:00
timothyandClaude Opus 5	af39123e8e	fix(616): fix a live 1-based SPA caller and un-cap two MCP playout tools ... Findings from the cold cross-family review of 8d35a279/5648f8e9. The review confirmed the three conclusions in 8d35a279 (the offset math is sound on all 12 paged endpoints; the list DTO really did already carry ChannelId; the new tests are non-vacuous) but found the previous commits had documented a convention without checking who actually violates it. HIGH — a live instance of this issue's own bug class, in the SPA. web/src/screens/SchedulesScreen.tsx asked for the rerun-collection picker with `pageNum: 1, pageSize: 1000`. pageNum is 0-based and pageSize clamps to 100, so the request skipped the first 100 rows: with <=100 rerun collections (the normal case) the picker was served an EMPTY page and silently offered no rerun collections at all; above 100 it dropped rows 1-100. Exactly the silent-short-set failure #616 is about, shipped in the UI. Now `pageNum: 0`, with a vitest that asserts the offset and is mutation-verified (restoring `pageNum: 1` fails it). Checked the rest of the SPA rather than assuming: every other pageNum caller is 0-based. CollectionsScreen's paging loop starts at 1 but only after fetching page 0 explicitly, so it is correct — verified before touching it. MEDIUM — two MCP tools wrapped paged endpoints while declaring no paging args. ersatztv_list_playouts and ersatztv_get_playout_items had no pageNum/pageSize, and ToolArgumentValidator rejects undeclared arguments, so an agent was hard capped at the first 100 rows with no way to ask for more and no error saying so. Both now take Page(). A catalog-wide sweep confirmed these were the only two: the other paged endpoints are not exposed as MCP tools at all. That same gap made the new ToolCatalog test vacuous in the direction that mattered — it filtered on tools that ALREADY declare pageNum, so a tool missing paging entirely escaped it. It now pins the expected set by name, so a new tool over a paged endpoint has to be added deliberately. Record corrections (these are read as normative, so over-broad claims are defects): "every wrapper says 0-based" was false for the OpenAPI surface, whose 12 pageNum parameters carry no description — named as a remaining gap instead of claimed as done. "Every controller floors with Math.Max" ignored SearchController's Math.Clamp. The ids-in-rows corollary was stated as an audit result when PlayoutListItemResponseModel.ScheduleName has no schedule id; restated as a rule about actionable ids. Verification: .NET 1900 + MCP 59 pass; web 996 pass across 105 files; tsc clean; eslint clean; format gate exit 0; no BOMs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:41:54 +02:00
timothyandClaude Opus 5	5648f8e92e	docs(616): scope the pageSize cap per endpoint — it is not one number ... Self-review of the previous commit caught an overclaim I introduced. I wrote the paging docs as if the pageSize cap were uniformly 100. It is not: most reads (collections, library browse, logs, playouts) Math.Clamp(.., 1, 100) GetAutoTuneChannelMembers pageSize <= 0 ? 100 : Min(.., 200) GET /api/v1/search/all-items default 500, cap 1000 That made a concrete example in docs/mcp.md simply false. It claimed `pageSize=500&pageNum=1` returns items 101-200 "not 501-1000" — but ersatztv_search_all_items also takes Page(), and 500 is UNDER its cap, so there page 1 really is items 501-1000. A caller following that example on the one tool most likely to be paged hard would have mis-derived its offsets, which is the same class of silent-short-set error this issue is about. The invariant that actually holds everywhere is the derivation, not any single cap: the offset comes from the EFFECTIVE (bounded) page size, never the requested one. Reworded to say that, in docs/mcp.md, the api.paging-zero-based record (rule + mechanics + body), and the ToolCatalog Page() comment. Catalog regenerated. The record's mechanics line no longer claims every controller uses Math.Clamp — ChannelController does not. No behaviour change; MCP suite still 59/59. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:24:40 +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
timothy	fba5233caf	feat(610): split the decision corpus into one YAML-frontmatter file per record ... 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	2026-07-25 19:45:09 +02:00