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
This commit is contained in:
2026-07-25 19:14:48 +02:00
parent 8578dc1ca7
commit 2dcc88a325
179 changed files with 6843 additions and 5983 deletions
@@ -0,0 +1,49 @@
---
key: ffmpeg.qsv-decode-encode-split
title: 2026-07-20 (#498) — QSV decode is split from QSV encode via a single `QsvPreferNativeDecoder` bool
status: active
since: '2026-07-20'
supersedes: none
superseded-by: none
rule: QSV decode is decoupled from QSV encode via a single `FFmpegProfile.QsvPreferNativeDecoder` bool (default ON, Linux-only), so a QSV encode profile can decode with the more tolerant native VA-API decoder instead of the QSV decoder, mirroring Jellyfin's hybrid decode/encode toggle instead of a general decode-family enum.
signals: 'QSV, native VA-API decode, Dolby Vision passthrough, hybrid decode/encode, HDR tonemap fallback · paths: `FFmpegProfile.QsvPreferNativeDecoder`, `QsvPipelineBuilder.SetTonemap`, `QsvPipelineBuilder` · issues: #498, #505'
mechanics: '`docs/superpowers/specs/2026-07-20-qsv-native-decode-design.md`; migration `HasDefaultValue(true)` on the nullable `bool?` column; `QsvPipelineBuilder` decoder-mode branch'
---
`FFmpegProfile.HardwareAcceleration` picked one pipeline builder for **both** decode and encode, so an
Intel QSV profile decoded with the QSV decoder — which is materially less tolerant of imperfect H.264 than
FFmpeg's native VA-API decoder and cannot carry Dolby Vision metadata. Jellyfin, on identical hardware,
avoids this by decoding with VA-API and encoding with QSV; that combination was not expressible in
ErsatzTV. Full design: `docs/superpowers/specs/2026-07-20-qsv-native-decode-design.md`.
- **Chosen: a single, QSV-scoped `FFmpegProfile.QsvPreferNativeDecoder` boolean**, mirroring Jellyfin's
"Prefer OS native DXVA or VA-API hardware decoders" checkbox exactly — Jellyfin itself deliberately
collapses this to one default-on toggle rather than a decode-family picker, and copying the reference
tool's granularity avoids over-building past a problem it has already solved.
- **Default ON.** Native VA-API decode is strictly more tolerant of imperfect streams than the QSV decoder
wrapper, and Dolby Vision passthrough requires it — so the working configuration *is* the default for a
reliability fix. Existing QSV profiles adopt the hybrid on upgrade via the migration's
`HasDefaultValue(true)` (SQLite `INTEGER`/MySQL `tinyint`, **nullable with `DEFAULT 1`** — the column
is `bool?` so an explicit `false` persists, while `NULL`/absent reads as ON via `!= false`; a
non-nullable `bool` + store default would make EF silently drop a create-with-`false`), no opt-in required.
- **Rejected: a general `DecodeHardwareAcceleration` enum column** decoupling decode and encode hardware
families entirely. More configurable than Jellyfin's own control, but nothing in the codebase or the
reported failure needs that generality yet — `FFmpegState` already separates
`DecoderHardwareAccelerationMode` / `EncoderHardwareAccelerationMode` internally (used today for the
software-decode-plus-hardware-encode error-loop fallback), so the seam to grow into a real enum exists
if a second asymmetric-decode case ever shows up on another hardware family. Deferred rather than
built now, on YAGNI grounds.
- **Contained to the QSV builder.** The flag does not touch `PipelineBuilderFactory`'s single-builder
dispatch per profile, and does not repurpose the existing decode/encode-mode fields into a general
cross-family selector — that repurposing is exactly the rejected enum option, just introduced through
the back door.
- **Accepted trade-off — HDR tonemapping runs in software on the native path.** With native decode ON the
decoder mode is `Vaapi`, so `QsvPipelineBuilder.SetTonemap` (which only selects `TonemapQsvFilter` for
`DecoderHardwareAccelerationMode == Qsv`) falls to the software `zscale`/`tonemap` chain for HDR content.
Output is correct but costs CPU on the realtime path. Accepted for now because software tonemap is
correct-but-slower while an unvalidated GPU-tonemap graph could be worse (needs the Intel host to
verify), and the escape hatch covers it: HDR-on-QSV users who don't need the tolerant decoder set the
flag OFF to keep GPU tonemap. Optimizing the native path to `tonemap_qsv` is tracked in **#505**.
- **Native decode is Linux-only.** Guarded with `!OperatingSystem.IsWindows()` in the QSV builder —
FFmpeg has no `vaapi` hwaccel on Windows (and Windows QSV capabilities are over-reported), so on Windows
a QSV profile keeps QSV decode regardless of the flag.