docs(integer_adm): verify + defer Netflix#955 i4_adm_cm rounding overflow (ADR-0155)

[lusoris]

Summary

Addresses Netflix upstream issue #955 ("Weird rounding in i4_adm_cm", OPEN since 2020). add_bef_shift_flt[idx] = (1u << (shift_flt[idx] - 1)) in libvmaf/src/feature/integer_adm.c scales 1–3 overflows int32_t (1u << 31 = 0x80000000 wraps to -2147483648). Every downstream (prod + add_bef_shift) >> 32 then subtracts 2^31 instead of adding it — ADM scales 1–3 are biased low by ≈1 LSB per summed term.

Verified present in fork PR #44's verbatim port of Netflix 966be8d5 at integer_adm.c:1277,1281 + :2000,2004.

Decision: leave the bug in place. The buggy arithmetic is encoded in the Netflix golden assertAlmostEqual values (project hard rule #1 / ADR-0024). Unilaterally fixing it would diverge from every published VMAF number calibrated on these outputs. Netflix has not responded to Netflix#955 in ~6 years — no upstream authority to track under the ADR-0142 carve-out yet.

Scope

Documentation-only — zero code change.

• New docs/adr/0155-adm-i4-rounding-deferred-netflix-955.md — pins the decision, runner-up options, sync criteria.
• libvmaf/src/feature/integer_adm.c — warning comments at both add_bef_shift_flt[] initialiser loops (scales 1–3, two occurrences in the file). No code change.
• libvmaf/src/feature/AGENTS.md — "Rebase-sensitive invariants" entry pinning the decision for future maintainers.
• docs/rebase-notes.md — entry 0048 (re-test via make test-netflix-golden on upstream sync).
• docs/adr/README.md — ADR-0155 index row.
• CHANGELOG.md — "Documented (not fixed)" subsection under lusoris-fork Unreleased.

Test

• meson test -C build → 35/35 pass (bit-identical to pre-PR).
• clang-tidy -p build libvmaf/src/feature/integer_adm.c → zero new warnings (the 430 pre-existing warnings are historical debt from the upstream-mirror port, out of scope for this doc-only PR; none are in the WarningsAsErrors set).
• pre-commit run --files <touched> → all hooks pass.

Type

• docs — documentation

Checklist

• Commits follow Conventional Commits.
• Pre-commit hooks green locally.
• Unit tests pass: meson test -C build → 35/35.
• Zero code change → Netflix golden gate untouched.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.
• This PR intentionally preserves the buggy ADM arithmetic that underlies those golden numbers; the decision is documented in ADR-0155.

Cross-backend numerical results

N/A — zero code change; no numerical path modified.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: upstream issue is linked directly from the ADR; no separate digest warranted for a doc-only defer decision.
• Decision matrix — ADR-0155 §Alternatives considered (4 options: leave / opt-in flag / fix + golden update / unconditional widen).
• AGENTS.md invariant note — libvmaf/src/feature/AGENTS.md under "Rebase-sensitive invariants".
• Reproducer / smoke-test command — pasted below under Reproducer.
• CHANGELOG.md "lusoris fork" entry — under ### Documented (not fixed).
• Rebase note — entry 0048 in docs/rebase-notes.md.

Reproducer

Verifying the overflow is present (no build needed):

grep -n "add_bef_shift_flt\[idx\] = (1u" libvmaf/src/feature/integer_adm.c
# Expect: two hits — around line 1281 (i4_adm_cm scale loop) and
# line 2004 (i4_adm_csf_den_scale scale loop). Both assign
# `1u << 31 = 0x80000000` into `int32_t`.

Demonstrating the overflow behaviour (tiny standalone C, no libvmaf needed):

#include <stdio.h>
#include <stdint.h>
int main(void) {
    uint32_t shift_flt = 32;
    int32_t add_bef_shift_flt = (1u << (shift_flt - 1));
    printf("%d (expected +2147483648)\n", add_bef_shift_flt);
    /* prints: -2147483648 (expected +2147483648) */
    return 0;
}

Verifying the Netflix golden numbers are unchanged by this PR:

ninja -C build
make test-netflix-golden
# Expect: VMAF mean 76.66890... on src01_hrc00/01_576x324 golden pair.

Known follow-ups

• If Netflix ever lands a fix upstream (widening add_bef_shift_flt[] to uint32_t or int64_t), sync under the ADR-0142 Netflix-authority carve-out: C-side fix + updated assertAlmostEqual values in the same merge. Remove the in-file warning comments; flip ADR-0155 to Superseded by ADR-NNNN.
• The 430 pre-existing clang-tidy warnings in integer_adm.c (mostly bugprone-macro-parentheses + readability-isolate-declaration from the upstream-mirror port) are historical debt; out of scope for this PR. Future ADR-0141 sweep should pick them up.

🤖 Generated with Claude Code