fix(gpu): collapse the four divergent ADM angle_flag predicates onto one

[lusoris]

What

decouple()'s integer-ADM 1-degree angle_flag test had four different
spellings in the tree (T-UPSTREAM-930, Netflix/vmaf#930):

Site	Evaluation
integer_adm.c, adm_avx2.c, adm_avx512.c	narrow each int64 operand to float, compare in double — the golden-frozen form
CUDA / HIP decouple_angle_flag_s0	compare the exact int64 products in double
CUDA / HIP decouple_angle_flag_s123	the golden form — so s0 and s123 disagreed inside one backend
SYCL integer_adm_sycl.cpp (both scales)	the whole comparison in float
Metal iadm_angle_flag_s0	exact int64 products narrowed to float

angle_flag selects the enhancement-gain-limited branch of decouple(), so a
flipped flag moves adm scores.

The predicate now lives once, in core/src/feature/adm_angle_flag.h:

• adm_angle_flag_fp64() — the golden expression, verbatim. Scalar CPU, CUDA
  and HIP call it, at both scales.
• adm_angle_flag_i64() — a bit-identical evaluation in 64-bit integer
  arithmetic using no floating point of any width. SYCL calls it (Intel Arc
  A-series and most iGPUs expose no fp64, and one fp64 instruction anywhere in
  that TU makes the runtime reject the whole SPIR-V module — the binary
  confirms it: SYCL: device lacks native fp64); metal/integer_adm.metal
  mirrors it in MSL, which has no double type at all.

The CPU expression is untouched — core/src/feature/integer_adm.c compiles to
byte-identical machine code against origin/master.

Why it is reachable

Instrumenting the scalar CPU adm_decouple() to evaluate all four historical
forms per scale-0 pixel:

Clip	scale-0 pixels	CUDA/HIP flips	SYCL flips	Metal flips
src01_hrc00/hrc01_576x324 (the Netflix golden pair)	1 540 608	0	2	3
sparks_ref/dis_480x270 10-bit	111 870	0	1	0
synthetic full-contrast 1080p noise, ±1 LSB distortion	1 017 036	11	11	18

Reproducer / smoke-test command

# 1. the regression test (host-only, no GPU)
meson setup core/build-cpu -Denable_cuda=false -Denable_sycl=false
ninja -C core/build-cpu -j 4 test/test_adm_angle_flag
core/build-cpu/test/test_adm_angle_flag        # 7 tests run, 7 passed

# 2. prove the CPU/golden lane did not move
git show origin/master:core/src/feature/integer_adm.c > /tmp/old.c
cc -Icore/build-cpu/src -Icore/src -Icore/src/feature -Icore/src/feature/common \
   -Icore/include -Icore/build-cpu/include -O3 -std=c23 -D_GNU_SOURCE -fPIC \
   -DVMAF_BUILDING_LIBVMAF -DVMAF_HAVE_DNN=1 -c core/src/feature/integer_adm.c -o /tmp/new.o
cc <same flags> -c /tmp/old.c -o /tmp/old.o
objdump -d --no-show-raw-insn /tmp/old.o | tail -n +3 > /tmp/a
objdump -d --no-show-raw-insn /tmp/new.o | tail -n +3 > /tmp/b
diff /tmp/a /tmp/b && echo "CPU code unchanged"

# 3. SYCL end-to-end on the golden pair (Arc A380), adm_enhn_gain_limit=1.2
source /opt/intel/oneapi/setvars.sh
CXX=icpx CC=icx meson setup core/build-sycl -Denable_sycl=true -Denable_cuda=false
ninja -C core/build-sycl -j 4
core/build-sycl/tools/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 --backend sycl --model path=<v0.6.1 + adm_enhn_gain_limit=1.2> \
  --json --precision max -o /tmp/sycl.json

Evidence

Regression test, both directions. With adm_angle_flag_i64()'s body
temporarily replaced by the pre-fix SYCL all-float predicate:

test_cos_constant_is_one_float_everywhere: pass
test_golden_expression_on_divergent_quads: pass
test_legacy_gpu_forms_are_the_divergent_ones: pass
test_i64_helper_matches_golden_on_divergent_quads: fail
adm_angle_flag_i64 must match the golden angle_flag
4 tests run, 1 failed

With the shipped helper:

test_cos_constant_is_one_float_everywhere: pass
test_golden_expression_on_divergent_quads: pass
test_legacy_gpu_forms_are_the_divergent_ones: pass
test_i64_helper_matches_golden_on_divergent_quads: pass
test_i64_helper_handles_degenerate_operands: pass
test_i64_helper_matches_golden_on_scale0_sweep: pass
test_i64_helper_matches_golden_on_boundary_walk: pass
7 tests run, 7 passed

SYCL on the Arc A380, golden 576x324 pair, 48 frames, adm_enhn_gain_limit=1.2:

max |CPU - SYCL| over adm metrics:
   legacy float predicate : 1.174971e-05
   shared int64 predicate : 8.219720e-07
legacy vs fixed SYCL: 6 of 240 adm metrics changed (frames 3, 23, 30)

CUDA on the RTX 4090, synthetic noise clip, adm_enhn_gain_limit=1.2:

integer_adm2_egl_1.2        0.9993743386943251 -> 0.9993743655248627
integer_adm3_egl_1.2        0.9996871693471625 -> 0.9996871827624314
integer_adm_scale0_egl_1.2  0.999429676185588  -> 0.9994297761196714

Only scale 0 moves — exactly the site the CUDA/HIP change touches. At the
shipped default adm_enhn_gain_limit = 1.0 the flag gates only the
MIN(rst, t) clamp, which is frequently a no-op, and the CUDA adm output on
that clip is byte-identical before and after.

Fuzz. adm_angle_flag_i64() vs the golden expression: 200 000 000 scale-0
band quadruples and 103 813 779 boundary-walk triples spanning all 62 magnitude
classes plus a 20x20x20 edge-operand cube — 0 mismatches, repeated under
gcc and clang at -O0, -O2 -ffp-contract=off and -O3 -march=native.

Suite. meson test -C core/build-cpu --suite=fast → Ok: 115, Fail: 0.

Lint. clang-tidy -p core/build-tidy reports 0 diagnostics on both
core/src/feature/integer_adm.c and core/test/test_adm_angle_flag.c
(-Db_lto=false, per the tidy-lane note). pre-commit run --files <all touched>
is clean.

Not verified here

• HIP was changed identically to CUDA (the two files are byte-for-byte twins
  for this helper) but not executed — the AMD iGPU lane was not exercised.
• Metal cannot be built or run on Linux; its MSL mirror is verified only by
  review against the C header that the unit test pins. core/src/feature/AGENTS.md
  now records that the mirror is manual and must be edited in lockstep.
• The nightly cuda / hip / sycl clang-tidy ratchet lanes (they do not
  run on PRs) may report a stale-high baseline for the three touched backend
  files, since the change removes inline expressions from them. The cpu lane —
  the one that gates PRs — is unaffected: neither touched cpu-lane file appears
  in scripts/ci/tidy-baseline-cpu.json and both measure 0.

Deep-dive deliverables

• Research digest — docs/research/2030-adm-angle-flag-fp64-free.md

• Decision matrix — ADR-1194 ## Alternatives considered (six rows)

• AGENTS.md invariant note — core/src/feature/AGENTS.md, "angle_flag has exactly one definition"

• Reproducer / smoke-test command — above

• CHANGELOG fragment — changelog.d/fixed/adm-angle-flag-predicate-divergence.md

• Rebase note — docs/rebase-notes.md, "fix/t-upstream-930-adm-angle-flag"

• ADR: docs/adr/1194-adm-angle-flag-single-source.md + index row

• docs/state.md updated (row moved to Recently closed)

• no docs needed: no user-discoverable surface changes — no new CLI flag, C API,
  build option, feature name or output key; the only user-visible effect is that
  GPU adm values move toward the CPU reference, which is what the ADR and the
  changelog fragment record.

• no ffmpeg patch impact: no public header, CLI flag or meson_options.txt
  entry changes.

Closes T-UPSTREAM-930-ADM-ANGLE-FLAG-PREDICATE-DIVERGENCE-2026-09-03.
Refs Netflix/vmaf#930.

🤖 Generated with Claude Code