Skip to content

docs(adr): ADR-0767 Phase 4b.8 — libvmaf C ABI break scoping (v4.0.0) - #109

Closed
lusoris wants to merge 1 commit into
masterfrom
worktree-agent-ae269c3d3818cdc79
Closed

lusoris wants to merge 1 commit into
masterfrom
worktree-agent-ae269c3d3818cdc79

Conversation

@lusoris

@lusoris lusoris commented May 29, 2026

Copy link
Copy Markdown
Contributor

Summary

  • DO NOT MERGE — scoping/design document for review before implementation begins.
  • ADR-0767 records the Phase 4b.8 decision to break the libvmaf C ABI for VMAFx v4.0.0.
  • Research-0752 provides the full symbol inventory and detailed rationale.

What is in this PR

  • docs/adr/0767-phase-4b8-c-abi-break-scoping.md — ADR (status: Proposed)
  • docs/research/research-0752-phase-4b8-c-abi-break-scoping.md — complete scoping digest:
    • Full symbol inventory across all 14 public headers
    • Table of all entry points consumed by ffmpeg-patches/0001–0015
    • 9 proposed breaking changes with rationale
    • v4.0.0 version bump plan
    • ffmpeg-patches rewrite plan (lockstep per CLAUDE.md §12 r14)
    • Migration guide outline (v3→v4 table + sed script sketch)
    • Test plan (golden assertions unaffected, new v4 smoke tests, series replay gate)

Proposed breaking changes (summary)

# Change Rationale
1 Config structs pass-by-const-pointer Future-proof struct extension without binary break
2 Remove vmaf_write_output Superseded by vmaf_write_output_with_format (ADR-0119)
3 Remove vmaf_model_load string-lookup Replace with vmaf_model_version_next + vmaf_model_load_builtin
4 void→int for destroy/free/close family Error-detectable cleanup
5 Rename vmaf_sycl_picture_fetch Naming consistency with CPU and CUDA equivalents
6 Move SYCL entry points to libvmaf_sycl.h Wrong include namespace
7 Add vmaf_context_get_backend Removes external backend tracking
8 soname 3→4 Required by all ABI changes above
9 ffmpeg-patches 0001–0015 rewrite Mandatory per CLAUDE.md §12 r14

Netflix golden assertions

Unaffected — they are CLI tests, not C ABI tests.

Deliverables checklist (ADR-0108)

  • Research digest: docs/research/research-0752-phase-4b8-c-abi-break-scoping.md
  • Decision matrix: ADR-0767 ## Alternatives considered
  • AGENTS.md invariant note: no rebase-sensitive invariants (doc-only PR)
  • Reproducer / smoke-test: no source changes — read the digest and ADR
  • Changelog fragment: changelog.d/changed/0767-phase-4b8-c-abi-break-scoping.md
  • Rebase notes: entry added to docs/rebase-notes.md

🤖 Generated with Claude Code

…so.4

Scoping document and research digest for the authorized VMAFx v4.0.0 ABI
break. No source changes — design approval gate only.

Deliverables:
- docs/adr/0767-phase-4b8-c-abi-break-scoping.md (ADR, Proposed)
- docs/research/research-0752-phase-4b8-c-abi-break-scoping.md
  (full symbol inventory across 14 public headers + 15 ffmpeg-patch
  callsite tables, 9 proposed breaking changes, v4 migration guide outline,
  test plan, ffmpeg-patches rewrite plan)
- docs/adr/README.md — index row added
- docs/rebase-notes.md — entry added
- changelog.d/changed/0767-phase-4b8-c-abi-break-scoping.md

Breaking changes proposed for v4.0.0:
1. Config structs from pass-by-value to const*
2. Remove vmaf_write_output (superseded by vmaf_write_output_with_format)
3. Remove vmaf_model_load string-lookup (use vmaf_model_version_next +
   new vmaf_model_load_builtin)
4. void->int return for destroy/free/close family
5. Rename vmaf_sycl_picture_fetch -> vmaf_sycl_fetch_preallocated_picture
6. Move vmaf_read_pictures_sycl/vmaf_flush_sycl to libvmaf_sycl.h
7. Add vmaf_context_get_backend + VmafBackend enum
8. ffmpeg-patches 0001-0015 rewrite in lockstep (CLAUDE.md 12 r14)

DO NOT MERGE -- requires user review before implementation begins.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lusoris
lusoris force-pushed the worktree-agent-ae269c3d3818cdc79 branch from b87d4ee to f437401 Compare May 29, 2026 12:08
@lusoris
lusoris marked this pull request as ready for review May 31, 2026 13:50
@lusoris

lusoris commented May 31, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by master merge marathon 2026-05-31.

@lusoris lusoris closed this May 31, 2026
@lusoris
lusoris deleted the worktree-agent-ae269c3d3818cdc79 branch May 31, 2026 13:53
@lusoris
lusoris restored the worktree-agent-ae269c3d3818cdc79 branch May 31, 2026 18:48
@lusoris lusoris reopened this May 31, 2026
@lusoris
lusoris marked this pull request as draft May 31, 2026 18:50
@lusoris

lusoris commented Jun 3, 2026

Copy link
Copy Markdown
Contributor Author

Closing in favor of rebased PR from branch c-abi-break-0767-rebase (conflict-free, pre-commit clean).

@lusoris lusoris closed this Jun 3, 2026
lusoris added a commit that referenced this pull request Jun 3, 2026
Scoping document and research digest for the authorized VMAFx v4.0.0 ABI
break. No source changes — design approval gate only.

Deliverables:
- docs/adr/0767-phase-4b8-c-abi-break-scoping.md (ADR, Proposed)
- docs/research/research-0752-phase-4b8-c-abi-break-scoping.md
  (full symbol inventory across 14 public headers + 15 ffmpeg-patch
  callsite tables, 9 proposed breaking changes, v4 migration guide outline,
  test plan, ffmpeg-patches rewrite plan)
- docs/adr/README.md — index row added
- docs/rebase-notes.md — entry added
- changelog.d/changed/0767-phase-4b8-c-abi-break-scoping.md

Breaking changes proposed for v4.0.0:
1. Config structs from pass-by-value to const*
2. Remove vmaf_write_output (superseded by vmaf_write_output_with_format)
3. Remove vmaf_model_load string-lookup (use vmaf_model_version_next +
   new vmaf_model_load_builtin)
4. void->int return for destroy/free/close family
5. Rename vmaf_sycl_picture_fetch -> vmaf_sycl_fetch_preallocated_picture
6. Move vmaf_read_pictures_sycl/vmaf_flush_sycl to libvmaf_sycl.h
7. Add vmaf_context_get_backend + VmafBackend enum
8. ffmpeg-patches 0001-0015 rewrite in lockstep (CLAUDE.md 12 r14)

Rebased from PR #109 (05-29 vintage) onto current master.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lusoris added a commit that referenced this pull request Jun 3, 2026
…#561)

Scoping document and research digest for the authorized VMAFx v4.0.0 ABI
break. No source changes — design approval gate only.

Deliverables:
- docs/adr/0767-phase-4b8-c-abi-break-scoping.md (ADR, Proposed)
- docs/research/research-0752-phase-4b8-c-abi-break-scoping.md
  (full symbol inventory across 14 public headers + 15 ffmpeg-patch
  callsite tables, 9 proposed breaking changes, v4 migration guide outline,
  test plan, ffmpeg-patches rewrite plan)
- docs/adr/README.md — index row added
- docs/rebase-notes.md — entry added
- changelog.d/changed/0767-phase-4b8-c-abi-break-scoping.md

Breaking changes proposed for v4.0.0:
1. Config structs from pass-by-value to const*
2. Remove vmaf_write_output (superseded by vmaf_write_output_with_format)
3. Remove vmaf_model_load string-lookup (use vmaf_model_version_next +
   new vmaf_model_load_builtin)
4. void->int return for destroy/free/close family
5. Rename vmaf_sycl_picture_fetch -> vmaf_sycl_fetch_preallocated_picture
6. Move vmaf_read_pictures_sycl/vmaf_flush_sycl to libvmaf_sycl.h
7. Add vmaf_context_get_backend + VmafBackend enum
8. ffmpeg-patches 0001-0015 rewrite in lockstep (CLAUDE.md 12 r14)

Rebased from PR #109 (05-29 vintage) onto current master.

Co-authored-by: Lusoris <lusoris@pm.me>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@lusoris
lusoris deleted the worktree-agent-ae269c3d3818cdc79 branch June 4, 2026 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant