docs(adr): accept the VMAFx API redesign and VMAFx filter names for RC4 (ADR-1852)

[lusoris]

Summary

Records the maintainer's RC4 decisions of 2026-10-05 as ADR-1852 (Accepted): a new VMAFx C API generated with every other surface from one definition, libvmaf.h kept as a separate thin compatibility library, and every FFmpeg filter capability continued under a VMAFx name. Docs only; it lands before the RC4 code so the RC4 work packages have a settled decision to build on. The prototype slice stays draft PR #2173.

Decisions recorded (all popup answers, references verbatim in the ADR):

• D1 one TOML definition (core/api/vmafx.toml) + standard-library Python generators; generated files committed and drift-checked.
• D2 libvmafx.so.1, pkg-config libvmafx, ABI 1.0.0 frozen at the v1.0.0 tag.
• D3 libvmaf.so.3 as a separate thin library on the exported vmafx_ symbols.
• D4 vmafx filter with backend + device; upstream option names kept as aliases.
• D5 own VMAFX_* status codes with a generated errno map.
• D6 every filter capability survives under a VMAFx name, none under a vmaf name: vmafx (replacing libvmaf, libvmaf_cuda, libvmaf_sycl, libvmaf_metal, libvmaf_vulkan and the HIP option), vmafx_tune (replacing libvmaf_tune), vmafx_pre (replacing vmaf_pre), -vmafx-profile (replacing -vmaf-profile); the ADR lists every old option and its new spelling.
• D7 deprecation warnings on libvmaf.h opt-in in 1.0, default in 1.1, removed in 2.0.
• D8 one import retry after a host wait on the acquire fence, then fail naming backend, input, formats, plane and refusing extractors; never a silent host copy.

Also: ADR-1685 (API shape) and ADR-0686 (library and filter names) are marked superseded in part with the repository's status-line pattern (bodies untouched); docs/roadmap.md RC4 scope and exit boundary name the change; Research-2158 holds the design review.

Type

• docs — documentation only

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• make format && make lint is green locally — commit hooks (markdownlint, generated-docs freshness, ADR checks) pass.
• Unit tests pass — not applicable: no code changed.
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. — not applicable.
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. — not applicable.
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header — not applicable.
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: — not applicable: a decision record; the RC4 changes it governs carry their own migration notes.
• If this PR adds an ADR, the ADR row lives in docs/adr/_index_fragments/<NNNN-slug>.md and the slug is appended to docs/adr/_index_fragments/_order.txt.

Bug-status hygiene (ADR-0165)

• docs/state.md updated — no state delta: decision record only; it opens, closes and rules out no bug.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.
• If I believe a golden value must change, I have explained why below — not applicable.

Deep-dive deliverables (ADR-0108)

• Research digest — docs/research/2158-vmafx-api-redesign.md.
• Decision matrix — ADR-1852 ## Alternatives considered (API, generation, SONAME, compat packaging, status codes, FFmpeg names, deprecation, import failure, phase).
• AGENTS.md invariant note — no rebase-sensitive invariants: decision record only; the invariants arrive with the RC4 code (feat(api): generate the VMAFx C API from one definition (RC4 prototype, ADR-1852) #2173 carries them for its slice).
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/changed/adr-vmafx-api-redesign.md.
• Rebase note — no rebase impact: docs only, no code or generated file of an upstream sync changes.

Reproducer

make docs-fragments-check
python3 scripts/ci/check-source-adr-citations.py

Known follow-ups

• RC4 work packages WP1-WP12 (Research-2158 section 6) build on this record; the prototype slice is draft PR feat(api): generate the VMAFx C API from one definition (RC4 prototype, ADR-1852) #2173 (label rc4).
• Research number 2158 was chosen by hand (no allocator for digests); renumber on a collision.