fix(libvmaf): score_pooled returns -EAGAIN for pending features (Netflix#755, ADR-0154)

[lusoris]

Summary

Addresses Netflix upstream issue #755 ("VMAF functions exit with error when vmaf_read_pictures and vmaf_score_pooled calls are interleaved", OPEN).

Root cause: integer_motion's motion2/motion3 (and the 5-frame-window variant) write frame N's score retroactively when frame N+1 is extracted — and the tail on flush. So at the instant vmaf_read_pictures(ctx, ref, dist, i) returns, frame i's motion2 is not yet in the feature collector. vmaf_feature_collector_get_score returned -EINVAL in that case — indistinguishable from genuine misuse (bad pointer, out-of-range, unknown feature).

Fix: split the error code.

• -EAGAIN → feature index is valid but not yet written (transient; retry after one more vmaf_read_pictures or after flush).
• -EINVAL → genuine misuse (null pointer, i >= capacity, unknown feature name).

Downstream integrations that want per-frame streaming VMAF output can now distinguish transient-retry from abort-now. Upstream maintainer closed the door on the streaming use case in 2020 ("you cannot call vmaf_score_pooled() in a loop"); the fork reopens it with one changed error code and one inline-helper signature tweak — no change to the retroactive-write design.

Scope

• libvmaf/src/feature/feature_collector.c:vmaf_feature_collector_get_score — the "not written" branch returns -EAGAIN.
• libvmaf/src/feature/feature_collector.h:vmaf_feature_vector_get_score (inline fast-path) — splits the previous combined return -1 into -EINVAL (null / out-of-range) and -EAGAIN (not written). Added #include <errno.h>.
• Drive-by (ADR-0141 touched-file rule): rename reserved __VMAF_FEATURE_COLLECTOR_H__ header guard to VMAF_FEATURE_COLLECTOR_INCLUDED.

Supported streaming pattern (documented via the new test):

for (unsigned i = 0; i < N; i++) {
    vmaf_read_pictures(ctx, &ref, &dist, i);
    if (i >= 2) {
        /* 3-frame motion window: after reading i, frame i-2 is complete. */
        vmaf_score_pooled(ctx, model, MEAN, &score, i - 2, i - 2);
    }
}
vmaf_read_pictures(ctx, NULL, NULL, 0);  /* flush → retroactive tail */
for (unsigned i = 0; i < N; i++)
    vmaf_score_pooled(ctx, model, MEAN, &score, i, i);

Test

New libvmaf/test/test_score_pooled_eagain.c with 4 subtests:

1. returns_eagain_on_pending — submit frames 0 + 1 then score_pooled(1,1) must return -EAGAIN (motion2 for frame 1 not written yet).
2. streaming_pattern — after read(3), score_pooled(0,0) and score_pooled(1,1) both succeed with finite scores.
3. after_flush_complete — after flush, every in-range index is poolable.
4. still_rejects_bad_range — inverted range + NULL score pointer still return -EINVAL (not -EAGAIN).

Reducer confirmed: git stash push libvmaf/src/feature/feature_collector.{c,h} && ninja -C build && meson test -C build test_score_pooled_eagain reports Fail: 1.

Type

• fix — bug fix

Checklist

• Commits follow Conventional Commits.
• Pre-commit hooks green locally.
• Unit tests pass: meson test -C build → 35/35.
• clang-tidy -p build libvmaf/src/feature/feature_collector.{c,h} → zero warnings.
• Reducer verified fail-without-fix / pass-with-fix.
• Visible behaviour change flagged under ### Changed in CHANGELOG.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Cross-backend numerical results

N/A — error-code split; no numeric path changed.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: error-code split.
• Decision matrix — ADR-0154 §Alternatives considered.
• AGENTS.md invariant note — fork-ahead -EAGAIN/-EINVAL split in rebase-notes 0047.
• Reproducer / smoke-test command — pasted below under Reproducer.
• CHANGELOG.md "lusoris fork" entry — under ### Changed.
• Rebase note — entry 0047 in docs/rebase-notes.md.

Reproducer

ninja -C build
meson test -C build test_score_pooled_eagain
# Expect: 4/4 subtests pass

# Reducer confirmation:
git stash push libvmaf/src/feature/feature_collector.c libvmaf/src/feature/feature_collector.h
ninja -C build && meson test -C build test_score_pooled_eagain
# Expect: Fail: 1 (tests fail without the -EAGAIN split)
git stash pop

Issue-matching standalone reproducer (loop of read + per-frame pool):

read_pictures(0) -> 0
score_pooled(0,0) -> rc=0 score=97.428043
read_pictures(1) -> 0
score_pooled(1,1) -> rc=-11 score=97.428043   # -EAGAIN (was -EINVAL)
read_pictures(2) -> 0
score_pooled(2,2) -> rc=-11 score=97.428043   # -EAGAIN
flush -> 0
final_pool(0..2) -> rc=0 score=97.428043

Known follow-ups

• A future vmaf_feature_available_up_to(ctx, unsigned *i_max) polling API could build on this. Out of scope for this PR; the -EAGAIN signal is the minimal contract.

🤖 Generated with Claude Code