fix(cli): run --feature on the explicit --backend's twin and report what ran

[lusoris]

Summary

With an explicit --backend cuda|sycl|hip|metal, vmaf --feature <cpu-name> now runs that backend's twin: vmaf --backend sycl --feature ciede runs ciede_sycl instead of the CPU extractor. When there is no twin, or the twin cannot honour an option or the input size, the CPU extractor runs and the CLI prints one warning line that names the feature and the reason. The JSON backend_used now reports the backend the extractors actually ran on, and a new feature_backends array lists each extractor's backend, so a mixed run says so.

Stacked on #1616 (perf/sycl-ciede-throughput), rebased onto its current head 39c7880e5. It must merge after #1616: it moves #1616's T-CLI-FEATURE-NAME-BYPASSES-GPU-BACKEND-2026-09-29 row to Recently closed and rewrites the #1616 CLI-guide paragraph and changelog bullet that describe the old behaviour. The base is master, so until #1616 merges the diff also shows its commits.

This implements the maintainer's popup decision of 2026-09-29, "CLI picks the twin (Recommended)" (ADR-1359).

How the twin is chosen

The CLI links the shared libvmaf, which hides its registry (-fvisibility=hidden, ADR-0379), so this PR adds two additive public functions to libvmaf.h:

• vmaf_feature_backend_twin() pairs a CPU extractor with the imported backend's twin through the lookup model dispatch already uses (its provided features through vmaf_get_feature_extractor_by_feature_name(), restricted to the backend's flag, so no name table). It accepts the twin only if it honours every option (ADR-1183 / ADR-1316) and passes the ADR-1324 geometry check for the input. It registers nothing.
• vmaf_registered_feature_extractor() lists the registered extractors and the backend each runs on. The CLI reads it after the final flush to build the receipt.

Unchanged: twin names such as --feature ciede_sycl (and their ADR-0543 exit 100), --backend cpu, --backend auto, no --backend, vmaf_use_feature(), and the FFmpeg filters. ffmpeg-patches/ needs no change: no patch references the new symbols or backend_used, and the filters keep registering by exact name.

Type

• feat — new feature
• fix — bug fix
• perf — performance improvement
• refactor — no behavior change
• docs — documentation only
• test — test-only
• build / ci — tooling / infra
• port — cherry-pick from upstream Netflix/vmaf
• sycl / cuda / simd — backend-specific

Checklist

• Commits follow Conventional Commits (the commit-msg hook enforces this).
• make format && make lint is green locally. Run piecewise, see "Verification" below: clang-format 23.1.1, the scoped clang-tidy 22.1.8 CPU-lane ratchet, shellcheck, shfmt, markdownlint and make docs-fragments-check are clean on the touched files.
• Unit tests pass: python3 scripts/ci/run_meson_test.py -- -C build. The fast suite passes except four tests that fail identically on the base without this change (see "Verification").
• If I touched any SIMD/GPU code path, I ran /cross-backend-diff and the worst ULP is ≤ 2. No kernel changed; the mapped run is bit-identical to the explicit twin on all 48 Netflix frames.
• If I touched a feature extractor with SIMD/GPU twins, I either updated every twin or listed the gap under "Known follow-ups" below. No extractor changed.
• If I added a new .c / .cpp / .cu / .h / .hpp, it has the appropriate license header (see CONTRIBUTING.md).
• If this is a breaking change, the commit message uses ! or BREAKING CHANGE: and the migration path is documented below. Not breaking: the C API and the JSON schema only grow.
• 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 — do not edit docs/adr/README.md directly (regenerated by scripts/docs/concat-adr-index.sh; see ADR-0221).

Bug-status hygiene (ADR-0165)

• docs/state.md updated in this PR with a row in the appropriate section. T-CLI-FEATURE-NAME-BYPASSES-GPU-BACKEND-2026-09-29 moves to Recently closed. T-SYCL-PSNR-HVS-B580-SIGSEGV-2026-09-29 opens under RC2 stabilisation: psnr_hvs_sycl crashes on the Arc B580 with or without this change, and --backend sycl --feature psnr_hvs now reaches it.

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 AND pinged @lusoris for a CODEOWNERS exception. Not applicable.

Cross-backend numerical results

No kernel changed. --feature ciede --backend sycl against --feature ciede_sycl --backend sycl on the B580:

ciede2000  Netflix 576x324, 48 frames, --precision max  mapped == explicit on every frame; max |sycl - cpu| = 1.18e-5
ciede2000  BBB 3840x2160, 22 frames                      mapped == explicit on every frame

Performance (if perf or feat)

Not a perf change, but the reported symptom was throughput. BBB 3840x2160 on the B580, wall time including start-up: 22 frames in 395 ms with --feature ciede --backend sycl (504 ms with the explicit twin name, same scores), against 787 ms per frame for serial CPU ciede on the same host while other builds ran. Research-2120 measured 1714 ms per frame for the old --feature ciede --backend sycl.

Deep-dive deliverables (ADR-0108)

• Research digest — Research-2121: why the CLI needs a library query, why the per-feature lookup must be restricted to the backend flag and scan every provided feature, the measured SYCL pairing table for 25 CPU extractors, and the receipt design. Research-2120's open question now points to it.
• Decision matrix — in ADR-1359 ## Alternatives considered: resolving in vmaf_use_feature(), fixing only the receipt, a CLI name table, exporting the internal registry, failing without a twin, a "mixed" value, and requiring full feature coverage.
• AGENTS.md invariant note — core/tools/AGENTS.md "--feature twin routing and backend receipt (ADR-1359)": the pairing lives in libvmaf only, the ADR-0543 gate runs first, the warning prints before the options are consumed, and backend_used gains fields, never values.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/cli-feature-backend-twin.md and changelog.d/added/libvmaf-feature-backend-twin-api.md; CHANGELOG.md re-rendered.
• Rebase note — docs/rebase-notes.md "fix/cli-feature-backend-twin — --feature runs the explicit --backend's twin (ADR-1359)".

Reproducer

# Needs a SYCL build and an Intel GPU; swap sycl for cuda / hip / metal.
vmaf --reference python/test/resource/yuv/src01_hrc00_576x324.yuv \
     --distorted python/test/resource/yuv/src01_hrc01_576x324.yuv \
     --width 576 --height 324 --pixel_format 420 --bitdepth 8 \
     --no_prediction --backend sycl --feature ciede --feature brisque \
     --json --output /tmp/out.json
# stderr: vmaf: warning: --feature brisque: the sycl backend has no twin of this extractor; computing it on the CPU
# /tmp/out.json ends with:
#   "backend_used": "sycl", "feature_backends": [{"extractor": "ciede_sycl", "backend": "sycl"}, {"extractor": "brisque", "backend": "cpu"}]

# Device-free tests, and the device run (skips with 77 without a GPU):
python3 scripts/ci/run_meson_test.py -- -C build test_cli_feature_backend test_feature_backend_twin \
    test_vmaf_feature_backend_cpu test_vmaf_feature_backend_sycl

Verification

Run in vmaf-dev-mcp:local on the WSL2 workstation, B580 as level_zero:0:

• SYCL build (icx, AOT bmg-g21,adl-s, -Db_lto=false; with LTO the tests that link only libvmaf.a fail to link on the base too, because GNU ar does not index LLVM bitcode): test_cli_feature_backend (14 cases, libvmaf replaced by fakes), test_feature_backend_twin (9 cases, white-box against the real SYCL registry), test_vmaf_feature_backend_cpu, test_vmaf_feature_backend_sycl, test_feature_collector, test_feature_extractor, test_context, test_cli_parse, test_sycl_ciede_parity and test_vmaf_sycl_threads pass.
• Fast suite: 227 of 232 pass. test_sycl_psnr_hvs_parity and _large (SIGSEGV), test_sycl_adm_tiny_frames and test_gpu_picture_pool_uaf (timeout) fail the same way in a build with this PR's library diff reverted; test_meson_secret_env_sanitization failed once on container clock skew.
• Netflix golden subset: vmafexec_test.py and vmafexec_feature_extractor_test.py, 141 passed against a gcc CPU build.
• clang-tidy 22.1.8, CPU lane, scoped to libvmaf.c, feature_extractor.cpp, vmaf.cpp and the new files: 0 findings in each; libvmaf.h stays at its baseline of 7.
• make docs-fragments-check in python:3.14-slim, check-source-adr-citations.py, check-state-md-rows.sh, standardsctl compile-context --verify, standardsctl hiss coverage --verify and make dedupe-check pass. standardsctl audit fails on this Windows host with 148 unbaselined findings, reported as "0 in touched files"; a Linux build of praetor's current source reports none in touched files.

Known follow-ups

• T-SYCL-PSNR-HVS-B580-SIGSEGV-2026-09-29: psnr_hvs_sycl crashes on the B580 (the UHD 770 runs it). Until it is fixed, --backend sycl --feature psnr_hvs crashes on that GPU where it used to run on the CPU; --backend cpu avoids it.
• CUDA, HIP and Metal use the same lookup and are covered by the device-free tests; test_vmaf_feature_backend_{cuda,hip,metal} have not been run on those GPUs.
• The SYCL clang-tidy lane was not re-measured; the CPU lane covers every touched host TU.

🤖 Generated with Claude Code

no ffmpeg-patches update needed: the patches register extractors by exact name through vmaf_use_feature(), which is unchanged; no patch references vmaf_feature_backend_twin(), vmaf_registered_feature_extractor() or backend_used.