From 539fcde902a2b93542c6dbaaa0a581cfa6fdcebb Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 22 Aug 2026 16:04:36 +0200 Subject: [PATCH 01/21] feat(807): SPA full-replace bodies are built as Complete MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The six SPA screens that hand-build write-request objects field-by-field could silently drop a DTO field on a full-replace write — #754's mechanism narrowed to optional fields, filed as residue by `testing.full-replace-asserts-field-list`. The premise that residue was filed on turned out to be wrong, and the correction is the more useful half. The mechanism was LATENT, not live: the OpenAPI type generator renders a nullable DTO property as a required member of a nullable type (`"name": null | string`), not as an optional one, and none of the eleven request schemas these builders target declares a single `?:` member. tsc was already checking all of them. But it was doing so contingently — on a generator behaviour nothing asserts, for a set of DTOs none of which had yet acquired an optional property. Optional members already occur elsewhere in the same generated file, so the contingency was one modelling decision away from lapsing silently. `Complete` removes the contingency rather than asserting the generator's current behaviour: it maps a request type so every member is required, making an omission a hard error however the generator emitted it. Applied at the full-replace wrapper boundary so future callers inherit it without knowing it exists, and at each construction site, which is what keeps the excess-property (phantom-field) direction alive — two sites had lost it by building through an inferred local or a spread rather than a fresh annotated literal. Measured, not argued: injecting an optional member into `ScheduleItemRequest` reddens `normalizeForSave` with TS2741 under `Complete` and compiles CLEAN without it. Mutating `Complete` to drop `Required` reddens the guard's case 2; `Partial` reddens cases 2 and 4. Case 4 does not discriminate against the realistic mutation and the guard says so, because no real request type can today — which is the contingency itself. The proof ships as `@ts-expect-error` cases re-executed on every `npm run typecheck` (a marked CI step), not witnessed once by hand. Verification: typecheck clean, eslint clean, 1200 web tests pass (new guard test confirmed executed by name), 833 scripts/tests pass. fixes #807 Decisions-Edit: yes --- .../full-replace-asserts-field-list.md | 37 +++++- docs/spa-conventions.md | 32 +++++ web/src/api/blocks.ts | 5 +- web/src/api/completeRequest.guard.test.ts | 111 ++++++++++++++++++ web/src/api/completeRequest.ts | 57 +++++++++ web/src/api/decoTemplates.ts | 3 +- web/src/api/playlists.ts | 5 +- web/src/api/playouts.ts | 5 +- web/src/api/schedules.ts | 3 +- web/src/api/templates.ts | 3 +- web/src/schedules/itemRules.ts | 3 +- web/src/screens/BlocksScreen.tsx | 5 +- web/src/screens/DecoTemplatesScreen.tsx | 6 +- web/src/screens/PlaylistsScreen.tsx | 11 +- web/src/screens/PlayoutScheduleEditors.tsx | 31 +++-- web/src/screens/TemplatesScreen.tsx | 8 +- 16 files changed, 288 insertions(+), 37 deletions(-) create mode 100644 web/src/api/completeRequest.guard.test.ts create mode 100644 web/src/api/completeRequest.ts diff --git a/docs/decisions/records/testing/full-replace-asserts-field-list.md b/docs/decisions/records/testing/full-replace-asserts-field-list.md index 88f254898..aa23cc4a3 100644 --- a/docs/decisions/records/testing/full-replace-asserts-field-list.md +++ b/docs/decisions/records/testing/full-replace-asserts-field-list.md @@ -130,9 +130,34 @@ be a name matcher over handler classes ending `Replace…Handler`, which misses and flags the ones that do it correctly. Per-site derivation, applied when a full-replace path is touched, is the enforceable version. -**Residue, tracked rather than implied closed.** The SPA builds request objects field-by-field in six -screens (`normalizeForSave` and its equivalents). A *required* field omitted there fails `tsc`; an -*optional* field added to the DTO and not carried through compiles clean and drops silently — #754's -mechanism narrowed to optional fields, with no equivalent of the MCP write-tool test on the SPA side. -That is the highest-probability recurrence in the repo today and is filed separately rather than -folded in here. +**The SPA half, closed by #807 — and the premise this record stated for it was wrong.** The residue +recorded here was that the SPA builds request objects field-by-field in six screens +(`normalizeForSave` and its equivalents), so an *optional* field added to the DTO and not carried +through would compile clean and drop silently. On audit (2026-08-22) that mechanism was **latent, +not live**: `scripts/generate-openapi-types.mjs` renders a nullable DTO property as a REQUIRED +member of a nullable type (`"name": null | string`), not as an optional one, and not one of the +eleven request schemas those six builders target declares a single `?:` member. `tsc` was therefore +already checking all of them. The protection was real but *contingent* — on a generator behaviour +nothing asserts, for a set of DTOs none of which had yet acquired an optional property. Optional +members do occur elsewhere in the same generated file (the Auto-Tune lineup-request family), so the +contingency was one modelling decision away from lapsing, silently and with no other net watching. + +`Complete` (`web/src/api/completeRequest.ts`) removes the contingency instead of asserting the +generator's current behaviour: it maps a request type so every member is required, so a builder that +omits one fails `npm run typecheck` however the generator emitted it. It is applied at the +full-replace API-wrapper boundary — so future callers inherit it without knowing it exists — and at +each of the six construction sites, which is what keeps TypeScript's excess-property check (the +*phantom* direction) alive; two of those sites had lost it by building through an inferred local or +a spread rather than a fresh annotated literal. + +Measured rather than argued (2026-08-22): injecting an optional member into `ScheduleItemRequest` +reddens `normalizeForSave` with `TS2741` under `Complete`, and compiles **clean** without it — +the negative control is the defect itself. The proof ships as `@ts-expect-error` cases in +`web/src/api/completeRequest.guard.test.ts`, re-executed on every `npm run typecheck` (a marked CI +step) rather than witnessed once by hand. + +**Residue that remains**, stated rather than implied closed. `Complete` is shallow, so a NEW +nested item request type needs its own annotation and nothing forces that. It is applied to the +full-replace bodies only, not to the create/update endpoints. And the fixture caveat above still +applies here: requiring a field to be *named* is not the same as requiring it to be *populated* +correctly. diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md index 45764c1ec..5be68daea 100644 --- a/docs/spa-conventions.md +++ b/docs/spa-conventions.md @@ -407,6 +407,38 @@ spec-cased vs runtime-cased key (the old `PlaybackTroubleshootingScreen` `#198` `data.channel.fFmpegProfileId` has been removed — read `ffmpegProfileId` straight off the typed response). When you mock an API response in a test, use the generated (runtime) casing. +## 4b. Full-replace request bodies are built as `Complete` (#807) + +A full-replace endpoint writes the WHOLE entity, so a field the builder never sets is not left +alone — it is written as its default. Build every full-replace body against +`Complete` (`web/src/api/completeRequest.ts`), which maps a generated request type so **every** +member is required: + +```ts +function toReplaceRequest(draft: Draft): Complete { … } +items.map((item): Complete => ({ … })) +``` + +Two rules, and the second is the one that gets skipped: + +- **Annotate the wrapper parameter** (`body: Complete`) so every caller — + including ones written later by someone who never read this — inherits the check. +- **Annotate each construction site too**, including a `.map` callback's return type. The wrapper + annotation catches a *missing* field anywhere, but TypeScript's excess-property check (a + *phantom* field the schema does not accept) only fires on a **fresh object literal in a typed + position**. Building through an inferred local (`const buildRequest = () => ({ … })`) or a spread + (`...toRequestRecurrence(item)`) silently loses that direction — both had, before #807. + +An optional member may be written `field: undefined`. The point is not to forbid omitting a value, +it is to forbid omitting the *decision*: an unmentioned field is an oversight, an explicit +`undefined` is a choice a reviewer can see. + +Why this exists even though `tsc` appears to catch it already: it only does because the generator +happens to emit nullable properties as required-and-nullable (`"name": null | string`) rather than +optional. That is contingent, not guaranteed — see +`docs/decisions/records/testing/full-replace-asserts-field-list.md`, and +`web/src/api/completeRequest.guard.test.ts` for the executed proof. + ## 4a. Optimistic-concurrency editors (ETag / If-Match / 412) Replace-all editors (Blocks is the reference; see `api-conventions.md` §7a for the server contract, diff --git a/web/src/api/blocks.ts b/web/src/api/blocks.ts index 5340e7d94..82db428f8 100644 --- a/web/src/api/blocks.ts +++ b/web/src/api/blocks.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; @@ -60,7 +61,7 @@ export function getBlockItemsWithMeta(id: number): Promise, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/blocks/${id}`, { @@ -70,7 +71,7 @@ export function replaceBlock( }); } -export function previewBlock(id: number, body: ReplaceBlockRequest): Promise { +export function previewBlock(id: number, body: Complete): Promise { return request(`/api/v1/blocks/${id}/preview`, { body, method: 'POST' }); } diff --git a/web/src/api/completeRequest.guard.test.ts b/web/src/api/completeRequest.guard.test.ts new file mode 100644 index 000000000..e5e19291f --- /dev/null +++ b/web/src/api/completeRequest.guard.test.ts @@ -0,0 +1,111 @@ +import { describe, expect, it } from 'vitest'; +import type { Complete } from './completeRequest'; +import type { components } from './generated/v1'; + +/** + * #807 guard: the mutation proof for `Complete` (`./completeRequest.ts`). + * + * `Complete` is enforced by the COMPILER, not at runtime, so a vitest assertion cannot prove it + * works — a passing `expect` here would say nothing about whether the type still rejects an + * incomplete request. The proof is therefore the `@ts-expect-error` directives below, and it is a + * real one in the sense `testing.guard-ships-with-mutation-proof` requires: each directive + * INTRODUCES THE DEFECT the guard exists to catch, and `tsc` fails the build if the defect is NOT + * reported. A `@ts-expect-error` on a line that compiles cleanly is itself an error + * (`TS2578: Unused '@ts-expect-error' directive`), so weakening `Complete` — to + * `Partial`, to `T`, or by deleting the mapped type entirely — turns every case below red. + * That mutation runs on every `npm run typecheck`, which is a marked CI step + * (`docker-build.yml` → `ci-step-ran.sh mark typecheck`), rather than being executed once by hand + * and asserted in prose. + * + * Both directions are covered, because a MISSING field and a PHANTOM field are opposite defects: + * cases 2 and 4 are the missing direction (the #807 defect proper — a silently dropped field on a + * full-replace write), case 5 is the phantom direction. + * + * Cases 1-3 use a SYNTHETIC type so the proof cannot be invalidated by an unrelated schema change, + * and cases 4-5 use a REAL generated request type so the proof is demonstrably wired to + * `./generated/v1.d.ts` rather than only to a local fixture. Both are needed: the synthetic case + * alone would pass even if the generated types stopped being importable here, and the real case + * alone would break for reasons that have nothing to do with `Complete`. + * + * Note the deliberate shape of the synthetic type: `optionalMember?` is what the generator does + * NOT currently emit for these request schemas (see `./completeRequest.ts` for why, verified + * 2026-08-22). Case 2 is the whole point of this guard — it is the case that compiles clean + * WITHOUT `Complete`, which is why case 3 asserts exactly that. + */ + +type SyntheticRequest = { + requiredMember: string; + optionalMember?: number; + nullableMember: string | null; +}; + +// Case 1 — every member named, the optional one explicitly `undefined`: MUST compile. +// This is not filler. If `Complete` were written so that an optional member had to carry a +// real value, every builder would be forced to invent one, and the guard would be abandoned. +const case1: Complete = { + requiredMember: 'x', + optionalMember: undefined, + nullableMember: null +}; + +// Case 2 — the OPTIONAL member omitted: MUST be an error. This is #807's defect exactly. +// @ts-expect-error omitting an optional member of a Complete request must not compile +const case2: Complete = { + requiredMember: 'x', + nullableMember: null +}; + +// Case 3 — the SAME omission against the bare type: MUST compile. +// This is the negative control, and without it cases 2 and 4 prove nothing: it demonstrates that +// the error in case 2 comes from `Complete` and not from some other property of the object. +// It is the "compiles clean and is silently dropped" state #807 was filed about. +const case3: SyntheticRequest = { + requiredMember: 'x', + nullableMember: null +}; + +// Case 4 — a REAL generated request type with one member omitted: MUST be an error. +// `name` is omitted; `items` is present. If a future schema change removes `name`, this directive +// goes unused and tsc reports it, which is the correct outcome — the proof must be re-pinned to a +// member that still exists rather than silently degrading. +// +// What this case does and does NOT prove, measured 2026-08-22 rather than argued. Mutating +// `Complete` to `{ [K in keyof T]: T[K] }` (dropping `Required`, the realistic weakening) +// reddens case 2 ONLY; case 4 stays green. Mutating it to `Partial` reddens cases 2 and 4. +// So case 4 does not currently discriminate against the realistic mutation, and saying otherwise +// would be the failure this repo keeps recording. It cannot: `ReplaceDecoTemplateRequest.name` is +// already a REQUIRED member, so omitting it errors with or without `Complete`. No real request +// type here can discriminate today, because none has an optional member — which is precisely the +// contingency `./completeRequest.ts` exists to remove. Case 4's job is narrower and still worth +// having: it proves the generated schema is reachable from this guard and that `Complete` does +// not over-constrain a real request type. Case 2 is what proves the guard is load-bearing. +// @ts-expect-error omitting `name` from a real Complete must not compile +const case4: Complete = { + items: [] +}; + +// Case 5 — the PHANTOM direction: a field the schema does not accept: MUST be an error. +// The directive sits on the OFFENDING PROPERTY, not on the declaration: an excess-property error +// (TS2353) is reported at the property, whereas a missing-property error (TS2741, case 4) is +// reported at the declaration. Placing it on the declaration instead made tsc report the directive +// as unused AND the excess property as an error — two reds, not a proof. +const case5: Complete = { + name: 'x', + items: [], + // @ts-expect-error a field absent from the schema must not compile + fieldTheSchemaDoesNotHave: 1 +}; + +describe('#807 Complete request guard', () => { + it('is proven by the @ts-expect-error directives above, which npm run typecheck executes', () => { + // These runtime assertions exist only so the compile-time cases are REFERENCED. Without a use, + // `noUnusedLocals`/lint could remove them and the proof would vanish silently — the exact + // "a guard that never executed proves nothing" failure this repo has shipped before (#751). + // They deliberately assert almost nothing about behaviour: the guard is the compiler. + expect(case1.requiredMember).toBe('x'); + expect(case3.requiredMember).toBe('x'); + expect(case2).toBeDefined(); + expect(case4).toBeDefined(); + expect(case5).toBeDefined(); + }); +}); diff --git a/web/src/api/completeRequest.ts b/web/src/api/completeRequest.ts new file mode 100644 index 000000000..d00390e51 --- /dev/null +++ b/web/src/api/completeRequest.ts @@ -0,0 +1,57 @@ +/** + * `Complete` — a request type with every member REQUIRED, so a builder that forgets one + * fails `npm run typecheck` instead of silently dropping the field (issue #807). + * + * ## The defect this closes + * + * The SPA builds write-request bodies field-by-field as object literals against the generated + * schema types in `./generated/v1.d.ts`. Those bodies are sent to full-replace endpoints, so a + * field the builder never sets is not "left alone" — it is written as its default. That is #754's + * mechanism: a hand-maintained mirror drifts from a DTO by one field, the write returns HTTP 200, + * and the loss surfaces hours later. See `testing.full-replace-asserts-field-list`, whose "Residue" + * paragraph filed this gap. + * + * ## Why the compiler was not already catching it + * + * It was, but only by accident of how the generator emits. `scripts/generate-openapi-types.mjs` + * currently renders a nullable DTO property as a REQUIRED member of a nullable type + * (`"name": null | string`) rather than an OPTIONAL one (`"name"?: string`). A required member + * cannot be omitted, so today every builder is checked. Verified 2026-08-22: none of the request + * schemas these builders target (`ScheduleItemRequest`, `ReplaceBlockRequest`, `BlockItemRequest`, + * `ReplaceDecoTemplateRequest`, `DecoTemplateItemRequest`, `ReplaceTemplateRequest`, + * `TemplateItemRequest`, `ReplacePlaylistRequest`, `PlaylistItemRequest`, + * `PlayoutAlternateScheduleItemRequest`, `PlayoutTemplateItemRequest`) declares a single `?:` + * member. Optional members DO occur elsewhere in the same generated file (the Auto-Tune + * lineup-request family), so this is a property of which DTOs have been modelled so far, not a + * guarantee of the generator. + * + * That makes the protection CONTINGENT: the day one of those DTOs gains a genuinely optional + * property, `tsc` goes silent on it — by design, optional means omittable — and the silent drop is + * live with no other net watching. `Complete` removes the contingency by requiring every member + * at the construction site regardless of how the generator emitted it. + * + * ## Both directions + * + * - MISSING (a schema field the builder never sets) — `Complete` makes it a hard error, and it + * does so wherever the value is assigned, including through a spread or an inferred local. + * - PHANTOM (a field the builder sets that the schema does not accept) — TypeScript's excess + * property check already reports this, but ONLY for a "fresh" object literal in a typed + * position. So each construction site also carries an explicit `Complete<…>` annotation rather + * than relying on inference from an argument position two calls away; that is what keeps the + * literal fresh and this direction live. + * + * ## Explicit `undefined` is still allowed, deliberately + * + * `T[K]` is preserved, so an optional member may be written as `field: undefined`. The point is + * not to forbid omitting a value, it is to forbid omitting the DECISION — an unmentioned field is + * an oversight, `field: undefined` is a choice a reviewer can see. + * + * ## Shallow on purpose + * + * `Complete` does not recurse into `items: Array`. A deep variant would have to + * distinguish arrays, unions with `null`, and branded enum aliases, and would mangle them. Every + * nested item builder is a function in its own right here, so each is annotated + * `Complete` directly. A NEW nested request type therefore needs its own annotation; + * nothing forces that, and that residue is stated rather than implied closed (issue #807). + */ +export type Complete = { [K in keyof Required]: T[K] }; diff --git a/web/src/api/decoTemplates.ts b/web/src/api/decoTemplates.ts index d2d684bfd..567fb6991 100644 --- a/web/src/api/decoTemplates.ts +++ b/web/src/api/decoTemplates.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; @@ -57,7 +58,7 @@ export function getDecoTemplateItemsWithMeta(id: number): Promise, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/deco-templates/${id}`, { diff --git a/web/src/api/playlists.ts b/web/src/api/playlists.ts index 1b6fb3efc..d66c5cddf 100644 --- a/web/src/api/playlists.ts +++ b/web/src/api/playlists.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; @@ -55,7 +56,7 @@ export function createPlaylist(body: CreatePlaylistRequest): Promise { // the new ETag for a subsequent save (issue #253). export function updatePlaylist( id: number, - body: ReplacePlaylistRequest, + body: Complete, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/playlists/${id}`, { @@ -69,7 +70,7 @@ export function deletePlaylist(id: number): Promise { return request(`/api/v1/playlists/${id}`, { method: 'DELETE' }); } -export function previewPlaylist(body: ReplacePlaylistRequest): Promise { +export function previewPlaylist(body: Complete): Promise { return request('/api/v1/playlists/preview', { body, method: 'POST' }); } diff --git a/web/src/api/playouts.ts b/web/src/api/playouts.ts index 8137a3e78..00678e98e 100644 --- a/web/src/api/playouts.ts +++ b/web/src/api/playouts.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { useCallback, useEffect, useRef, useState } from 'react'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; @@ -179,7 +180,7 @@ export function getAlternateSchedulesWithMeta( */ export function replaceAlternateSchedules( playoutId: number, - body: ReplacePlayoutAlternateSchedulesRequest, + body: Complete, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/playouts/${playoutId}/alternate-schedules`, { @@ -204,7 +205,7 @@ export function getPlayoutTemplatesWithMeta(playoutId: number): Promise, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/playouts/${playoutId}/templates`, { diff --git a/web/src/api/schedules.ts b/web/src/api/schedules.ts index 234dee801..4c960d64b 100644 --- a/web/src/api/schedules.ts +++ b/web/src/api/schedules.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; // FillerPreset is exported by ./pickers — import (don't re-export) to avoid a duplicate `export *` @@ -67,7 +68,7 @@ export function addScheduleItem(scheduleId: number, body: ScheduleItemRequest): // response (see SchedulesScreen.tsx `save()`), not reuse the ids it submitted. export function replaceScheduleItems( scheduleId: number, - body: ReplaceScheduleItemsRequest, + body: Complete, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/schedules/${scheduleId}/items`, { diff --git a/web/src/api/templates.ts b/web/src/api/templates.ts index 50ee47fc5..703e70091 100644 --- a/web/src/api/templates.ts +++ b/web/src/api/templates.ts @@ -1,3 +1,4 @@ +import type { Complete } from './completeRequest'; import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client'; import type { components } from './generated/v1'; @@ -58,7 +59,7 @@ export function getTemplateItemsWithMeta(id: number): Promise, ifMatch?: string | null ): Promise> { return requestWithMeta(`/api/v1/templates/${id}`, { diff --git a/web/src/schedules/itemRules.ts b/web/src/schedules/itemRules.ts index 61740a54e..5885db683 100644 --- a/web/src/schedules/itemRules.ts +++ b/web/src/schedules/itemRules.ts @@ -1,6 +1,7 @@ // Pure, exhaustively-tested rules for the schedule-item editor. Encodes the Blazor // ProgramScheduleItemEditViewModel gating + forced-reset behavior (the parity standard for #207). // No React, no fetch — every function is a deterministic transform so itemRules.test.ts can pin it. +import type { Complete } from '../api/completeRequest'; import type { components } from '../api/generated/v1'; export type CollectionType = components['schemas']['CollectionType']; @@ -389,7 +390,7 @@ export function fromResponse(model: ScheduleItem): DraftItem { // Projects a draft to the request body, applying Blazor's getter-gating: gated-off values are // nulled (or defaulted to the enum's None) so the payload matches what a non-editing Blazor VM emits. -export function normalizeForSave(item: DraftItem): ScheduleItemRequest { +export function normalizeForSave(item: DraftItem): Complete { const isFixed = item.startType === 'Fixed'; const isMultipleCount = item.playoutMode === 'Multiple' && item.multipleMode === 'Count'; const isDuration = item.playoutMode === 'Duration'; diff --git a/web/src/screens/BlocksScreen.tsx b/web/src/screens/BlocksScreen.tsx index c518865b4..b739783aa 100644 --- a/web/src/screens/BlocksScreen.tsx +++ b/web/src/screens/BlocksScreen.tsx @@ -13,6 +13,7 @@ import { Trash2, TriangleAlert } from 'lucide-react'; +import type { Complete } from '../api/completeRequest'; import { navigateToPath } from '../routing'; import { Badge, @@ -206,7 +207,7 @@ function itemFromResponse(item: BlockItem): DraftItem { }; } -function toRequestItem(item: DraftItem): BlockItemRequest { +function toRequestItem(item: DraftItem): Complete { return { collectionType: item.collectionType, collectionId: item.collectionType === 'Collection' ? item.collectionId : null, @@ -269,7 +270,7 @@ function validate(draft: Draft): null | string { return null; } -function toReplaceRequest(draft: Draft): ReplaceBlockRequest { +function toReplaceRequest(draft: Draft): Complete { return { name: draft.name.trim(), minutes: draft.hours * 60 + draft.minutes, diff --git a/web/src/screens/DecoTemplatesScreen.tsx b/web/src/screens/DecoTemplatesScreen.tsx index f234c6918..64f3f24c9 100644 --- a/web/src/screens/DecoTemplatesScreen.tsx +++ b/web/src/screens/DecoTemplatesScreen.tsx @@ -20,8 +20,10 @@ import { type DecoListItem, type DecoTemplate, type DecoTemplateGroup, - type DecoTemplateItem + type DecoTemplateItem, + type DecoTemplateItemRequest } from '../api'; +import type { Complete } from '../api/completeRequest'; const BASE_PATH = '/app/deco-templates'; const MINUTES_PER_DAY = 24 * 60; @@ -604,7 +606,7 @@ function DecoTemplateEditor({ decoTemplateId }: { decoTemplateId: number }) { decoTemplateId, { name: draft.name.trim(), - items: draft.items.map((item) => ({ + items: draft.items.map((item): Complete => ({ decoId: item.decoId, startTime: item.startTime, endTime: item.endTime diff --git a/web/src/screens/PlaylistsScreen.tsx b/web/src/screens/PlaylistsScreen.tsx index 9f5a75648..a3c6ca35b 100644 --- a/web/src/screens/PlaylistsScreen.tsx +++ b/web/src/screens/PlaylistsScreen.tsx @@ -44,8 +44,10 @@ import { type PlaylistGroup, type PlaylistItem, type PlaylistItemRequest, - type PlaylistPreviewItem + type PlaylistPreviewItem, + type ReplacePlaylistRequest } from '../api'; +import type { Complete } from '../api/completeRequest'; import { SearchPicker } from '../schedules/pickers'; type CollectionType = PlaylistItemRequest['collectionType']; @@ -273,7 +275,7 @@ function draftFromItem(item: PlaylistItem): DraftItem { }; } -function toItemRequest(item: DraftItem, index: number): PlaylistItemRequest { +function toItemRequest(item: DraftItem, index: number): Complete { const source = configFor(item.collectionType)?.source ?? 'browse'; const trimmedCount = item.count.trim(); const parsedCount = trimmedCount === '' ? null : Number(trimmedCount); @@ -582,7 +584,10 @@ function PlaylistEditor({ playlistId, onBack, onSaved }: { playlistId: number; o }); }; - const buildRequest = () => ({ items: items.map(toItemRequest), name: name.trim() }); + const buildRequest = (): Complete => ({ + items: items.map(toItemRequest), + name: name.trim() + }); // Every item must carry a selection the API can bind. Without this the screen happily PUT an item // with a null id — the server 422s it (`ReplacePlaylistItemsHandler.CollectionTypeMustBeValid`), diff --git a/web/src/screens/PlayoutScheduleEditors.tsx b/web/src/screens/PlayoutScheduleEditors.tsx index d87287e85..c48937151 100644 --- a/web/src/screens/PlayoutScheduleEditors.tsx +++ b/web/src/screens/PlayoutScheduleEditors.tsx @@ -20,8 +20,11 @@ import { type PlayoutAlternateSchedule, type PlayoutTemplate, type ProgramSchedule, - type Template + type Template, + type PlayoutAlternateScheduleItemRequest, + type PlayoutTemplateItemRequest } from '../api'; +import type { Complete } from '../api/completeRequest'; const PLAYOUTS_PATH = '/app/playouts'; @@ -526,11 +529,13 @@ export function PlayoutAlternateSchedulesScreen({ playoutId }: { playoutId: numb replaceAlternateSchedules( playoutId, { - items: items.map((item) => ({ - id: item.id, - programScheduleId: item.programScheduleId, - ...toRequestRecurrence(item) - })) + items: items.map( + (item): Complete => ({ + id: item.id, + programScheduleId: item.programScheduleId, + ...toRequestRecurrence(item) + }) + ) }, etagRef.current ) @@ -830,12 +835,14 @@ export function PlayoutTemplatesEditorScreen({ playoutId }: { playoutId: number replacePlayoutTemplates( playoutId, { - items: items.map((item) => ({ - id: item.id, - templateId: item.templateId, - decoTemplateId: item.decoTemplateId, - ...toRequestRecurrence(item) - })) + items: items.map( + (item): Complete => ({ + id: item.id, + templateId: item.templateId, + decoTemplateId: item.decoTemplateId, + ...toRequestRecurrence(item) + }) + ) }, etagRef.current ) diff --git a/web/src/screens/TemplatesScreen.tsx b/web/src/screens/TemplatesScreen.tsx index cf8b6ab77..1f1a4bde6 100644 --- a/web/src/screens/TemplatesScreen.tsx +++ b/web/src/screens/TemplatesScreen.tsx @@ -21,8 +21,10 @@ import { type BlockGroup, type Template, type TemplateGroup, - type TemplateItem + type TemplateItem, + type TemplateItemRequest } from '../api'; +import type { Complete } from '../api/completeRequest'; const BASE_PATH = '/app/templates'; @@ -678,7 +680,9 @@ function TemplateEditor({ templateId }: { templateId: number }) { templateId, { name: draft.name.trim(), - items: draft.items.map((item) => ({ blockId: item.blockId, startTime: item.startTime })) + items: draft.items.map( + (item): Complete => ({ blockId: item.blockId, startTime: item.startTime }) + ) }, etagRef.current ); -- 2.47.3 From b8c1de3368637e809549cb9ffa085dfccc87f3f9 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 22 Aug 2026 22:20:49 +0200 Subject: [PATCH 02/21] fix(807): cover the two LIVE uncovered full-replace PUTs, correct four prose claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cold adversarial review returned BLOCKED. All findings confirmed by execution here before acting on them. H1 (blocker) — the change shipped with a live instance of the defect it claimed was latent. `MultiCollectionItemRequest.weight` and `UpdateFFmpegProfileRequest.qsvPreferNativeDecoder` are absent from their schemas' `required` arrays, so both emit optional, and both are the body of a full-replace PUT with a hand-built SPA body that the first commit did not cover. Deleting `weight: clampWeight(item.weight)` from `MultiCollectionsScreen.toItemRequest` typechecked CLEAN before this commit; the screen carries a prose comment warning that this exact drop resets every weight to 1 on save. It now reddens with TS2741. The bad reasoning is worth naming because it is a shape this repo keeps recording: "create/update" vs "replace" was sorted on the verb in the wrapper name rather than on what the endpoint does, and a property verified across the eleven schemas the six named builders touch was then reported as a property of the SPA. Coverage extended to `updateMultiCollection`, `updateFFmpegProfile`, `replaceDeco`, and both `mediaSources` replace wrappers. The FFmpeg fix surfaced a second instance one level down: the screen's `Draft` type and the `sampleRequest` test fixture both omitted `qsvPreferNativeDecoder`, so 30 green tests were exercising only the default. Both now `Complete<…>`. H3 — "two sites had lost the phantom direction" is five, and the stated cause was wrong. Measured: a fresh literal returned from a generic `.map` callback accepts a phantom field even with no spread and no inferred local, because `map` infers `U` from the callback rather than from the target element type. Three of the five contain neither a spread nor a local, so the documented rule would have taught a reader that those are safe. M4 — the generator was named as the cause of nullable-emits-as-required. It is a pass-through (`required.has(name) ? '' : '?'`); the determinant is the `required` array in the ASP.NET-produced `ErsatzTV/wwwroot/openapi/v1.json`. Pointed three durable places at the right file. M5 — the guard's header claimed every case reddens under every weakening, which its own case-4 comment contradicted. Replaced with the measured table. L6/L7/L8/N10 — record frontmatter now carries #807 so catalog-first lookup finds it (catalog regenerated); `guard-inventory.md`'s hand-written out-of-population list gains the third TS guard and now says why such a mirror goes stale silently; `Complete` exported from the api barrel; §4b moved after §4a. H2 is not fixed and is not implied closed: this guard proves `Complete`'s semantics, not that it is APPLIED — reverting one screen leaves it green. Filed as #820 and named as residue on the record. Verification: typecheck 0, eslint 0, 1200/1200 web tests, 833 passed 2 skipped in scripts/tests, catalog regenerates to a zero diff, doc-narrative 0 warnings. refs #820 Decisions-Edit: yes --- docs/decisions/README.md | 2 +- .../full-replace-asserts-field-list.md | 75 ++++++++++++------- docs/guard-inventory.md | 7 +- docs/spa-conventions.md | 70 +++++++++-------- web/src/api/completeRequest.guard.test.ts | 25 +++++-- web/src/api/completeRequest.ts | 58 +++++++------- web/src/api/decos.ts | 3 +- web/src/api/ffmpegProfiles.test.ts | 4 +- web/src/api/ffmpegProfiles.ts | 3 +- web/src/api/index.ts | 1 + web/src/api/mediaSources.ts | 5 +- web/src/api/multiCollections.ts | 3 +- web/src/screens/FFmpegProfilesScreen.tsx | 7 +- web/src/screens/MultiCollectionsScreen.tsx | 11 ++- 14 files changed, 168 insertions(+), 106 deletions(-) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index a9284d778..b20c68e00 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -201,7 +201,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `testing.e2e-local-fresh-config-dir` | Always point `scripts/e2e-local.sh` at a fresh config dir — leftover channels/schedules/DB rows bleed state between runs and corrupt assertions. (The *readiness-probe hang* this record was originally written about was fixed in #533; the fresh-dir rule stands on state-bleed grounds alone.) | 2026-07-21 | [link](records/testing/e2e-local-fresh-config-dir.md) | | `testing.enumerating-guard-identity-not-position` | A guard that cross-checks a hand-reviewed registry against call sites discovered across the whole repo must key each entry on properties INTRINSIC to the site — file, kind, and the value source text — and never on its absolute line or column. A registry keyed on position is a function of every other file in the repo, so a branch that never touches the guard can invalidate it; and because each PR is green against its own base, that failure is structurally invisible pre-merge and lands on `main` after review and after the merge gate. Dropping the position keeps every mutation the guard exists for — a NEW site, a REMOVED site and a CHANGED value each still fail, since each changes the identity multiset — and costs exactly ONE case, which must be stated rather than implied: a SAME-IDENTITY SUBSTITUTION within one file (delete a registered site, add a different unreviewed one with the same kind and value token, net-zero count) now passes. A REPORTED failure still prints the discovered line:column, because identity and diagnostics need not share a format. Comparison stays a MULTISET count rather than set membership, so two sites in one file sharing an identity must be discovered exactly that many times and a third occurrence still fails. A SCANNER test that asserts real AST positions against FIXED inline fixtures is the opposite case and keeps its line/column identity — it has no churn, because its input does not move. | 2026-07-27 | [link](records/testing/enumerating-guard-identity-not-position.md) | | `testing.fix-ships-a-witnessed-red-test` | A commit claiming to fix something may carry a `Proves: ` trailer; when it does, `scripts/prove-fix.sh` must show that selector GREEN with the fix and RED with the code side reverted, and CI enforces it per-PR. The trailer is opt-in — an unproven commit is allowed — but a claimed proof that does not hold fails the build. | 2026-08-16 | [link](records/testing/fix-ships-a-witnessed-red-test.md) | -| `testing.full-replace-asserts-field-list` | Any path that writes a WHOLE entity or a WHOLE child collection — a PUT-replace handler, a hand-built request object, a test comparer standing in for one — derives its field list from the authoritative type and asserts SET EQUALITY against it, rather than enumerating the fields by hand. A hand-written list is correct on the day it is written and structurally unable to report the day it stops being: the field that drifts is the one nobody wrote a line for, so no amount of care in the existing lines can reach it. The failure is silent by construction — a full replace with a field omitted returns HTTP 200 and destroys that field's value (#754 drifted from a 28-property DTO by one and cleared it; the symptom arrived hours later as missing pixels). SECOND CLAUSE, separable from the first: where a replaced child row carries state keyed to its identity — progression, ordering, an enumerator position — the handler RECONCILES BY ID rather than delete-and-reinsert, because reinsertion silently resets state a client never asked to touch (#252: a schedule PUT reset fill-group progression; #500: a dedup fix became permanent data loss because the add filter and the remove filter used different keys, so the two halves must agree on the key). Delete-and-reinsert is acceptable ONLY where no such state exists, and that emptiness is a fact about today's schema that a later feature can silently invalidate — so record it where the handler is, dated, rather than leaving it to be re-derived. The canonical worked example is `ToolCatalogTests.Every_Write_Tool_Should_Declare_Exactly_Its_OpenApi_Request_Body_Fields`, which reads the accepted fields from the generated OpenAPI document and compares both directions. | 2026-08-21 | [link](records/testing/full-replace-asserts-field-list.md) | +| `testing.full-replace-asserts-field-list` | Any path that writes a WHOLE entity or a WHOLE child collection — a PUT-replace handler, a hand-built request object, a test comparer standing in for one — derives its field list from the authoritative type and asserts SET EQUALITY against it, rather than enumerating the fields by hand. A hand-written list is correct on the day it is written and structurally unable to report the day it stops being: the field that drifts is the one nobody wrote a line for, so no amount of care in the existing lines can reach it. The failure is silent by construction — a full replace with a field omitted returns HTTP 200 and destroys that field's value (#754 drifted from a 28-property DTO by one and cleared it; the symptom arrived hours later as missing pixels). SECOND CLAUSE, separable from the first: where a replaced child row carries state keyed to its identity — progression, ordering, an enumerator position — the handler RECONCILES BY ID rather than delete-and-reinsert, because reinsertion silently resets state a client never asked to touch (#252: a schedule PUT reset fill-group progression; #500: a dedup fix became permanent data loss because the add filter and the remove filter used different keys, so the two halves must agree on the key). Delete-and-reinsert is acceptable ONLY where no such state exists, and that emptiness is a fact about today's schema that a later feature can silently invalidate — so record it where the handler is, dated, rather than leaving it to be re-derived. The canonical worked example is `ToolCatalogTests.Every_Write_Tool_Should_Declare_Exactly_Its_OpenApi_Request_Body_Fields`, which reads the accepted fields from the generated OpenAPI document and compares both directions. ON THE SPA SIDE the same rule is enforced by the TYPE SYSTEM rather than by a test: a full-replace body is built as `Complete` (`web/src/api/completeRequest.ts`), a mapped type that makes every member of a generated request type required, so a builder that omits one fails `npm run typecheck`. Annotate BOTH the API-wrapper parameter (so later callers inherit it) AND each construction site including every `.map` callback return type, because the excess-property check that catches a PHANTOM field fires only on a fresh literal in a contextually typed position and a generic `.map` callback is not one. Do not infer from "most builders already typecheck" that the gap is closed: a member is omittable exactly when it is absent from the schema `required` array in the ASP.NET-produced OpenAPI document, and two live cases (#807) sat unchecked inside a large majority of checked ones. | 2026-08-21 | [link](records/testing/full-replace-asserts-field-list.md) | | `testing.guard-derives-population-from-source` | A guard that asserts a COMPLETENESS property enumerates its population from a machine-readable authoritative source — the enum, the generated OpenAPI document, the parsed workflow YAML, the provider list — and asserts SET EQUALITY in BOTH directions against it. It may not narrow that population with a filter, a `Where`, a `grep` or an early `continue` before the assertion, because a filter cannot see the member that is MISSING: the member whose absence is the defect is precisely the one the predicate excludes. A hand-written literal list of members is the same defect in slower motion — a filter frozen at authoring time, correct on the day it was written and unable to report the day it stopped being. Two boundaries bound the rule rather than weaken it. FIRST, filtering to select the SUBJECT of a PER-MEMBER property is legitimate and is not this defect: the excluded members satisfy the property vacuously, so the filtered walk and the whole walk assert the same thing (`ToolCatalogTests.Every_Query_Parameter_Should_Be_A_Declared_Property` filters to tools that declare query parameters, and a tool declaring none has nothing to check). The defect is filtering the population before a COMPLETENESS claim, which is what makes an absent member unrepresentable (#757 filtered on `QueryParameters is {Count: > 0}` and so could not see a tool that should have declared one and did not). SECOND, a population of VALUES always has an external authoritative source and this rule applies directly; a population of SITES IN CODE has no such list, needs find-all-references tooling, and is tracked separately in #777 — do not stretch a set-equality assertion over it. Distinguish the guard SCOPE (which subsystems it covers — a reviewed policy choice, legitimately hand-written) from the guard POPULATION (the members inside that scope — always derived). When the scope itself MIRRORS an authoritative source, the mirror needs its own equality check or a dated staleness marker, or the guard is complete within a scope that has silently gone stale. The canonical worked example in this repo is `ToolCatalogTests.Every_Tool_Should_Declare_Exactly_Its_OpenApi_Query_Parameters`; the canonical residual gap is `MARKED_JOBS` in `scripts/tests/test_ci_dropped_step_guard.py`. WHEN THE POPULATION IS FILES (#806), the authoritative source is the GIT INDEX and never a filesystem walk. A walk is not merely a weaker enumerator, it answers a question about the MACHINE rather than about the repo: it reports build output, generated shims and editor droppings, and it differs between CI and every checkout, so the same guard asserts a different population in each place. Derive with `git ls-files`, take direct children only unless a nested population is stated and wanted, and assert existence rather than filtering on it, because filtering is what makes a missing member unrepresentable. This is an instantiation and not a blanket rewrite: the question per guard remains whether it makes a COMPLETENESS claim over TRACKED files, and a walk that assembles a fixture or selects the SUBJECT of a per-member property stays a walk with its reason written down. | 2026-08-13 | [link](records/testing/guard-derives-population-from-source.md) | | `testing.guard-ships-with-mutation-proof` | A guard is not considered tested because a test involving it passes. It ships with a MUTATION PROOF: remove or disarm THAT GUARD'S CLAUSE ALONE, and a NAMED test must go red. ONE NAMED EXCEPTION, with its limits, because the rule degenerates without it: where the guard IS a test (a checker enforcing a repo invariant, with no separate script behind it), disarming it makes it ABSENT rather than red, so the proof is the contrapositive — INTRODUCE THE DEFECT THE GUARD EXISTS TO CATCH into an isolated copy of the guarded artifact, and the named test must go red. That is a mutation of the guarded SYSTEM rather than of the assertion, and it is admissible ONLY for checker-guards and ONLY when the mutation was executed and witnessed. It is NOT a licence to grade an ordinary script-guard MUTATION for having a bad-input test: feeding a script an input its clause rejects is BEHAVIOUR-ONLY, which is what three rows were regraded for. A file-level grade under this exception covers the clause its cited case actually mutates, not every assertion that later lands in the same file. Three things this excludes, each of which has already shipped here as a green suite over a dead check. FIRST, a behavioural test — one that feeds the guard a good input and a bad input and checks it passes and fails — proves the guard REACTS, never that it is LOAD-BEARING; #685 had two guards on one condition where deleting either left the whole suite green while every behavioural test passed. SECOND, mutating the WHOLE FILE does not count (#510): a whole-file revert cannot show that a test reaches a particular clause, so the mutation must target the clause. THIRD, the guard being WIRED is not the guard RUNNING — #631's suite was invoked by no CI job, #751's step was dropped by the runner and the job reported success in 6s against a normal 14-17s, and #719's new logic was never connected to stdin. Every guard that DERIVES A POPULATION also carries an ANTI-VACUITY assertion, because the characteristic failure of a completeness check is reporting that it proved everything while its population was empty; a guard with no population has nothing for such an assertion to be about, and stating it universally reads as coverage the unproven rows do not have. Mechanical enforcement is possible for the BOOKKEEPING and not for the JUDGEMENT, and the split is the decision: `docs/guard-inventory.md` lists every guard file with its Kind, its Proof class (`MUTATION`/`BEHAVIOUR-ONLY`/`NONE`) and a `file::function` ref, and `scripts/tests/test_guard_inventory.py` derives the guard population from the GIT INDEX and the call sites (#806), asserts SET EQUALITY against the rows, and resolves every claimed ref to a real `def`. So a new guard cannot ship unclassified and a renamed test cannot leave a row silently claiming coverage. Whether a row claiming `MUTATION` is telling the truth is no longer left to review: `testing.mutation-claims-are-executed` (#790) requires each such row to carry a DECLARED clause mutation that is applied to an isolated copy of the repository on every run, with the row's own named test required to go red. | 2026-08-13 | [link](records/testing/guard-ships-with-mutation-proof.md) | | `testing.hook-reports-its-own-execution` | Every script in `.claude/hooks/` sources `scripts/hook-fire-log.sh` and calls `etv_hook_fire_begin