fix(gpu): cap the MS-SSIM dB output at max_db instead of clamping the linear score

[lusoris]

Summary

clip_db selects a ceiling on the dB output, derived once from the frame
geometry. float_ms_ssim.c:

const unsigned peak = (1 << bpc) - 1;
const double mse = 0.5 / (w * h);
s->max_db = clip_db ? ceil(10. * log10(peak * peak / mse)) : INFINITY;

static double convert_to_db(double score, double max_db)
{
    if (score >= 1.0) return max_db;              /* log10(0) would be -Inf */
    return MIN(-10. * log10(1.0 - score), max_db);
}

The CUDA, SYCL and HIP twins read it as a clamp on the linear score instead,
and none of the three carried a max_db field at all:

if (s->enable_db) {
    if (s->clip_db)
        score = score < 0.0 ? 0.0 : (score > 1.0 ? 1.0 : score);
    score = -10.0 * log10(1.0 - score);   /* unbounded */
}

Two consequences:

1. +Inf on an identical reference/distorted pair. MS-SSIM is 1.0, the
   clamp leaves it at 1.0, and -10 * log10(0) is +Inf. The CPU returns the
   finite max_db. Scoring a file against itself is an ordinary thing to do.
2. clip_db did not clip. Every high-similarity pair returned an unbounded
   dB value where the CPU caps it — the option's whole purpose.

Each twin now derives max_db in init() with the CPU's exact expression and
integer types, and converts through an ms_ssim_convert_to_db() helper that
mirrors the reference, short-circuit included.

Reproducer

meson setup build-cuda core -Denable_cuda=true -Denable_sycl=false -Db_lto=false
ninja -C build-cuda
meson test -C build-cuda test_cuda_float_ms_ssim_parity --print-errorlogs -v

Revert core/src/feature/cuda/ and the new variant fails with:

CUDA float_ms_ssim dB score is non-finite -- clip_db must cap it at max_db

Verified on an RTX 4090 (CUDA), an Arc A380 (SYCL) and gfx1030 (HIP) — each
unfixed twin returns a non-finite score against the CPU's finite max_db, and
each fixed twin matches. The pre-existing default-options parity tests stay
green.

source /opt/intel/oneapi/setvars.sh --force
CC=icx CXX=icpx meson setup build-sycl core -Denable_sycl=true -Denable_cuda=false -Db_lto=false
ninja -C build-sycl && meson test -C build-sycl test_sycl_ms_ssim_parity

meson setup build-hip core -Denable_hip=true -Denable_hipcc=true -Denable_cuda=false -Denable_sycl=false -Db_lto=false
ninja -C build-hip && meson test -C build-hip test_hip_ms_ssim_parity

The fixture had to saturate

The obvious variant — set enable_db=true, clip_db=true on the existing
fixture — passed against the unfixed twins. On a merely high-similarity pair
-10*log10(1 - score) sits well below max_db, so the ceiling never binds.
Only feeding the same picture as reference and distorted, driving MS-SSIM to
exactly 1.0, exposes it. A test for a saturating rule has to saturate; that is
written up in the digest.

Why the existing tests were blind

Every MS-SSIM parity test instantiated its extractors with NULL options, and
with enable_db off neither path converts to dB at all — the divergent code was
never executed. Same shape as ADR-1216 / ADR-1217 / ADR-1220, with one
difference: the twin was not ignoring the option, it was honouring a plausible
misreading of it. A grep for "is this option read anywhere?" finds clip_db and
moves on.

Scope

float_ms_ssim_metal.mm exposes only enable_lcs and rejects enable_db /
clip_db / enable_chroma outright, so it cannot emit a dB or chroma score at
all. That is a loud failure rather than a wrong answer — a feature gap, tracked
in docs/state.md rather than fixed here.

Deep-dive deliverables (ADR-0108)

• Research digest — docs/research/2038-clip-db-semantics-drift.md: a twin honouring a plausible misreading of an option name, and why the first version of the parity variant was green against the unfixed code.
• Decision matrix — docs/adr/1221-gpu-ms-ssim-db-ceiling.md ## Alternatives considered (four options; the runner-up "just guard score == 1.0" removes the +Inf but leaves clip_db still not clipping).
• AGENTS.md invariant note — new canonical note in core/src/feature/cuda/AGENTS.md, cross-referenced from core/src/feature/sycl/AGENTS.md, with a section in core/src/feature/hip/AGENTS.md.
• Reproducer / smoke-test command — see the Reproducer section above.
• CHANGELOG fragment — changelog.d/fixed/1221-gpu-ms-ssim-db-ceiling.md.
• Rebase note in docs/rebase-notes.md — entry ADR-1221 — MS-SSIM clip_db is a dB ceiling (2026-09-07).

Docs (rule 10)

docs/metrics/ms-ssim.md gains a note on what
clip_db means, what the twins did instead, and the instruction to re-measure
any GPU MS-SSIM dB score taken with it set.

Bug status (rule 13 / ADR-0165)

• docs/state.md — closes T-GPU-MS-SSIM-CLIP-DB-SEMANTICS-2026-09-07, and opens T-GAP-METAL-MS-SSIM-DB-CHROMA-OPTIONS-2026-09-07.

🤖 Generated with Claude Code