feat: scaffold Pelorus + smart-deband flagship (vf_pelorus_deband_vulkan)

Pelorus is a zero-copy GPU pre-encode pipeline: Vulkan compute + FFmpeg
filters that fix the psychovisual flaws of a hardware encoder in VRAM before
it sees the pixels, to close the BD-rate gap to CPU encoders. Codec-agnostic
(deband/denoise/motion help HEVC and AV1 alike; FGS covers AV1 AOM + HEVC/VVC
H.274). Sibling of VMAFx/vmafx (the quality oracle, which dropped Vulkan).

This initial scaffold lands:

- libpelorus: the Pelorus<->vmafx side-data interop ABI (interop.h/.c,
  versioned, UUID-keyed, append-only) + the smart-deband parameter contract,
  with a shared conformance fixture. Builds + tests green (meson).
- vf_pelorus_deband_vulkan: the flagship f3kdb-style smart deband (inline GLSL
  + side-data emit), shipped as ffmpeg-patches/0001 against n8.1.1 (applies via
  git am --3way). Standalone reference shader compiles to SPIR-V.
- Conventions adapted from golusoris + vmafx: principles.md, 8 ADRs, per-surface
  docs, changelog fragments, per-package AGENTS.md, ADR allocator.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lusoris

.clang-format

@@ -0,0 +1,31 @@
+---
+# Pelorus C style: K&R, 4-space, 100 columns. Matches the vmafx sibling so the
+# shared interop translation unit reads identically in both repos.
+BasedOnStyle: LLVM
+Language: Cpp
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ColumnLimit: 100
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterReturnType: None
+BinPackArguments: true
+BinPackParameters: true
+BreakBeforeBraces: Linux
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: false
+BreakStringLiterals: false
+ContinuationIndentWidth: 4
+DerivePointerAlignment: false
+PointerAlignment: Right
+ReflowComments: false
+SortIncludes: false
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: c++17
+IncludeBlocks: Preserve

.clang-tidy

@@ -0,0 +1,51 @@
+# See docs/principles.md §2 for the philosophy. Enables the families that map
+# directly to NASA Power-of-10, JPL-C-STD, CERT-C, and MISRA-C:2012 informative.
+# Mirrors the vmafx sibling's profile so the shared interop TU lints identically.
+
+Checks: >
+  -*,
+  bugprone-*,
+  cert-*,
+  clang-analyzer-*,
+  concurrency-*,
+  misc-*,
+  performance-*,
+  portability-*,
+  readability-braces-around-statements,
+  readability-function-size,
+  readability-isolate-declaration,
+  readability-misleading-indentation,
+  readability-non-const-parameter,
+  readability-redundant-control-flow,
+  -bugprone-easily-swappable-parameters,
+  -misc-include-cleaner,
+  -misc-no-recursion,
+
+WarningsAsErrors: >
+  bugprone-integer-division,
+  bugprone-infinite-loop,
+  cert-flp30-c,
+  cert-msc30-c,
+  clang-analyzer-core.*,
+  clang-analyzer-deadcode.DeadStores,
+  clang-analyzer-security.*,
+  performance-no-int-to-ptr
+
+# Lint Pelorus code; the FFmpeg patch sources under ffmpeg-patches/files/ build
+# against FFmpeg's tree and follow FFmpeg conventions, so they are excluded.
+HeaderFilterRegex: '^libpelorus/(include|src|test)/.*\.(h|hpp)$'
+
+FormatStyle: file
+
+CheckOptions:
+  - key: readability-braces-around-statements.ShortStatementLines
+    value: '2'
+  # Power-of-10 rule 4 — a function fits a printed page.
+  - key: readability-function-size.LineThreshold
+    value: '75'
+  - key: readability-function-size.StatementThreshold
+    value: '120'
+  - key: readability-function-size.BranchThreshold
+    value: '20'
+  - key: readability-function-size.NestingThreshold
+    value: '5'

.editorconfig

@@ -0,0 +1,25 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+[*.{c,h,cpp,hpp,cc,comp,glsl,vert,frag}]
+indent_size = 4
+
+[*.{js,ts,json,jsonc,yaml,yml,toml}]
+indent_size = 2
+
+[*.{md,rst}]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.{sh,bash}]
+indent_size = 4

.gitignore

@@ -0,0 +1,27 @@
+# Build trees (meson/ninja)
+/build/
+/build-*/
+/subprojects/*/
+!/subprojects/*.wrap
+
+# Compiled shaders / objects
+*.spv
+*.o
+*.obj
+
+# Local planning / session state (NOT tracked — see .workingdir/STATE.md
+# "How to use this file"; the vmafx convention + the user's global rule both
+# keep these local rather than committed).
+/.workingdir/
+/.scratch/
+
+# pkg-config / install staging
+/dist/
+
+# Editor / OS cruft
+*.swp
+*~
+.DS_Store
+/.cache/
+/.vscode/
+/compile_commands.json

AGENTS.md

@@ -0,0 +1,118 @@
+<!-- markdownlint-disable MD013 -->
+# Agent guide — Pelorus
+
+> Cross-tool context for Claude Code, Cursor, Aider, Codex, Continue, and other
+> coding assistants. **Read this before suggesting changes.** Then read the
+> per-subdirectory `AGENTS.md` for the area you're touching. Claude Code users:
+> [CLAUDE.md](CLAUDE.md) extends this file.
+
+## What this repo is
+
+`Pelorus` is a GPU **pre-encode** pipeline: Vulkan compute filters + FFmpeg
+filters that fix the psychovisual flaws of a hardware video encoder *before* it
+sees the pixels, entirely in VRAM (zero-copy). The goal is to close the BD-rate
+gap between fixed-function GPU encoders (NVENC/AMF/QSV) and slow CPU encoders
+(x265/SVT-AV1) — debanding, temporal denoise, film-grain synthesis, and
+optical-flow motion hints. These are **codec-agnostic**: deband/denoise/motion
+help HEVC (`hevc_nvenc`/`hevc_qsv`/`hevc_vaapi`/`hevc_amf`, rivaling x265) and
+AV1 equally; only film-grain is codec-specific (AV1 = AOM, HEVC/VVC = H.274).
+
+Pelorus is the sibling of **vmafx** (the VMAF fork), hosted under the same
+`vmafx` GitHub org. vmafx dropped its own Vulkan backend (its ADR-0726), so
+Pelorus is the Vulkan home; vmafx stays the **quality oracle**. The two are
+bidirectionally wired: Pelorus filters write a shared side-data blob that vmafx
+reads for perceptually-weighted scoring, and Pelorus tunes its filter strength
+against VMAF using vmafx's autotune loop. See
+[docs/architecture/overview.md](docs/architecture/overview.md) and
+[docs/principles.md](docs/principles.md).
+
+## Hard rules
+
+1. **Never break the `libpelorus` public ABI without a `Migration:` footer.**
+   The `PelorusSideData` interop blob is append-only (interop.h R1/R2): add a
+   field or section bit and bump `PELORUS_ABI_MINOR` — never reorder, resize, or
+   remove. A breaking change is forbidden; mint a new section bit instead.
+2. **All errors flow through `pel_result`.** No bare `return -1;` across a
+   `libpelorus` API boundary. Every non-void return is checked or `(void)`-cast.
+3. **No global mutable state / no static-init side effects.** Lifecycle is
+   explicit. Banned C functions: `gets`, `strcpy`, `strcat`, `sprintf`,
+   `strtok`, `atoi`, `atof`, `rand`, `system` (see docs/principles.md §1.2).
+4. **Keep the two deband implementations in lockstep.** The standalone
+   reference shader (`libpelorus/shaders/pelorus_deband.comp`) and the FFmpeg
+   filter's inline GLSL (`ffmpeg-patches/files/vf_pelorus_deband_vulkan.c`)
+   implement the same algorithm; edit both together.
+5. **Patch-stack sync.** A change to any `libpelorus` surface the FFmpeg patches
+   consume updates `ffmpeg-patches/files/` + the regenerated patch in the same
+   PR. Verify with a full series replay (`ffmpeg-patches/test/build-and-run.sh`),
+   not per-patch `git apply --check`.
+6. **Every PR leaves touched files lint-clean** to `-Wall -Wextra -Werror` +
+   clang-tidy. A `// NOLINT` carries an inline citation.
+7. **Every merged commit: 0 warnings · clang-tidy clean · `meson test
+   --suite=fast` green · the deband shader compiles (glslang).**
+
+See [docs/principles.md](docs/principles.md) for the full Power-of-10,
+SEI-CERT-C, style, and Vulkan-usage contract, and [CONTRIBUTING.md](CONTRIBUTING.md)
+for the per-PR deliverables (ADRs, per-surface docs, changelog fragments).
+
+## Repository layout
+
+```text
+Pelorus/
+├── meson.build  meson_options.txt   # build root (libpelorus + tests + shaders)
+│
+├── libpelorus/                       # the shared core (vendored by vmafx too)
+│   ├── include/pelorus/
+│   │   ├── pelorus.h                 #   umbrella: version, pel_result
+│   │   ├── interop.h                 #   the Pelorus<->vmafx side-data ABI
+│   │   └── deband.h                  #   smart-deband parameter contract
+│   ├── src/                          #   interop.c (pack/parse), deband_params.c
+│   ├── shaders/                      #   standalone reference .comp shaders
+│   └── test/                         #   interop ABI conformance fixture
+│
+├── ffmpeg-patches/                   # vf_pelorus_* filters, stacked vs n8.1.1
+│   ├── files/                        #   canonical filter sources (edit here)
+│   ├── 0001-*.patch  series.txt      #   generated artifacts + apply order
+│   ├── generate.sh                   #   regenerate patches from files/
+│   └── test/build-and-run.sh         #   apply + build + smoke-test gate
+│
+├── docs/
+│   ├── principles.md                 #   the coding + Vulkan-usage contract
+│   ├── adr/                          #   Architecture Decision Records (Nygard)
+│   ├── architecture/ api/ metrics/   #   per-surface docs (C4, interop, filters)
+│   ├── usage/ backends/ development/  #   pipeline, Vulkan path, build/release
+│   └── research/                     #   deep-dive digests
+│
+├── changelog.d/                      # Keep-a-Changelog fragments (rendered)
+└── AGENTS.md  CLAUDE.md  CONTRIBUTING.md  README.md
+```
+
+Per-subdirectory `AGENTS.md` files give unit-level conventions + the
+rebase-sensitive invariants.
+
+## Common tasks
+
+| Task | Command |
+|---|---|
+| Configure + build | `meson setup build && ninja -C build` |
+| Fast test gate | `meson test -C build --suite=fast` |
+| Install (for the FFmpeg patches) | `ninja -C build install` |
+| Regenerate FFmpeg patches | `cd ffmpeg-patches && ./generate.sh` |
+| Apply + build + smoke FFmpeg | `ffmpeg-patches/test/build-and-run.sh` |
+| Lint | `clang-format --dry-run -Werror` + `clang-tidy` on touched files |
+| Reserve an ADR number | `scripts/adr/next-free.sh --claim <slug>` |
+
+## Pinned upstream references
+
+| Component | Version |
+|---|---|
+| FFmpeg base for the patch stack | `n8.1.1` |
+| FFmpeg Vulkan filter model | `libavfilter/vf_gblur_vulkan.c`, `vf_nlmeans_vulkan.c` |
+| AV1 film-grain struct mirrored by interop §(d) | `libavutil/film_grain_params.h` |
+| vmafx control plane (autotune) | `libvmaf_tune` filter, `vmafx-server` `/v1/score`, `vmaf-mcp` |
+
+## When in doubt
+
+Read [docs/principles.md](docs/principles.md), then the per-subdirectory
+`AGENTS.md` for the area you're touching. Decisions live in
+[docs/adr/](docs/adr/); the project plan + current status live in
+`.workingdir/PLAN.md` + `.workingdir/STATE.md` (local, gitignored).

CHANGELOG.md

@@ -0,0 +1,31 @@
+<!-- markdownlint-disable MD013 MD024 -->
+# Changelog
+
+All notable changes to Pelorus are documented here. The format is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is
+[SemVer](https://semver.org/). The `[Unreleased]` block is **rendered** from
+`changelog.d/` fragments by `scripts/release/concat-changelog-fragments.sh` —
+do not edit it by hand (see [changelog.d/README.md](changelog.d/README.md)).
+
+## [Unreleased]
+
+### Added
+
+- **`libpelorus`** (`libpelorus/`): the shared core library — the Pelorus⇄vmafx
+  side-data interop ABI (`pelorus/interop.h`, `pelorus/interop.c`) and the
+  smart-deband parameter contract (`pelorus/deband.h`). The `PelorusSideData`
+  blob is a versioned, UUID-keyed, append-only AVFrame side-data format both
+  `vf_pelorus_*` and vmafx's `vf_libvmaf*` read/write. Ships a shared
+  conformance fixture (`libpelorus/test/interop_test.c`). ADR-0103, ADR-0105.
+- **`vf_pelorus_deband_vulkan`**: the flagship Vulkan compute smart-deband
+  filter — f3kdb-style flat-test + TPDF/blue-noise grain + a local-variance
+  detail-protection mask, zero-copy in VRAM. Shipped as
+  `ffmpeg-patches/0001-add-vf_pelorus_deband_vulkan.patch` against n8.1.1.
+  ADR-0102, ADR-0104.
+- **Reference shader** (`libpelorus/shaders/pelorus_deband.comp`): standalone
+  f3kdb deband, CI-compiled to SPIR-V.
+- **Project scaffold**: principles, ADRs (0001/0100/0102/0103/0104/0105/0106/0108),
+  per-surface docs, the FFmpeg patch tooling (`generate.sh`,
+  `test/build-and-run.sh`), and CI-style local gate.
+
+[Unreleased]: https://github.com/vmafx/pelorus/commits/master

CLAUDE.md

@@ -0,0 +1,79 @@
+<!-- markdownlint-disable MD013 -->
+# Claude Code guide — Pelorus
+
+> Claude Code-specific guide. For cross-tool conventions read [AGENTS.md](AGENTS.md)
+> first; this file extends it. Repo: `vmafx/pelorus` (hosted under the `vmafx`
+> GitHub org, alongside `VMAFx/vmafx`). Run `gh repo set-default vmafx/pelorus`
+> at the start of a session before any `gh` command.
+
+## What this is
+
+The GPU pre-encode sibling of vmafx. Vulkan compute + FFmpeg filters that
+pre-process frames in VRAM to close the BD-rate gap to CPU encoders. Flagship:
+`vf_pelorus_deband_vulkan` (smart deband). The shared `libpelorus` interop ABI
+is what makes Pelorus⇄vmafx bidirectional.
+
+## How to build / test
+
+```bash
+meson setup build && ninja -C build      # libpelorus + interop test + shader
+meson test -C build --suite=fast         # the pre-push gate
+ninja -C build install                   # install so the FFmpeg patches see it
+cd ffmpeg-patches && ./generate.sh        # regenerate the patch stack
+ffmpeg-patches/test/build-and-run.sh      # apply + build + smoke the filter
+```
+
+## Where the code is
+
+- `libpelorus/include/pelorus/interop.h` — the side-data ABI (the cross-repo
+  contract; append-only).
+- `libpelorus/src/interop.c` — pack/parse; **vendored verbatim by vmafx too**.
+- `libpelorus/shaders/pelorus_deband.comp` — standalone reference shader.
+- `ffmpeg-patches/files/vf_pelorus_deband_vulkan.c` — the in-tree filter (inline
+  GLSL). Keep its algorithm in lockstep with the `.comp`.
+
+## Tone
+
+- Be terse. No preamble.
+- When changing the `libpelorus` public ABI: write the `Migration:` footer in
+  the commit body, with before/after C snippets, and bump `PELORUS_ABI_MINOR`.
+- When adding a dependency: state the alternative you considered and why this
+  one wins, in the ADR.
+- Never add static-init side effects. Lifecycle is explicit.
+
+## Don't
+
+- Don't edit the two deband implementations independently — the `.comp` and the
+  filter's inline GLSL must stay in lockstep (AGENTS.md hard rule 4).
+- Don't reorder/resize/remove a field in any `PelorusSideData` struct — it is a
+  frozen wire ABI (interop.h R1/R2). Append only; new meaning = new section bit.
+- Don't hand-edit a generated `*.patch` — edit `ffmpeg-patches/files/` and rerun
+  `generate.sh`.
+- Don't `printf`/`fprintf(stderr,...)` from library code paths meant to be
+  embeddable; return a `pel_result` and let the host log.
+- Don't silence a linter without an inline justification next to the `// NOLINT`.
+- Don't create new top-level markdown docs unless the task needs them; extend
+  the existing `docs/` topic tree.
+
+## Per-PR deliverables (mirrors vmafx)
+
+Every non-trivial PR ships, in the same PR: an **ADR** (claim the number with
+`scripts/adr/next-free.sh --claim <slug>`), **per-surface docs** under `docs/`,
+a **changelog.d fragment**, and — for anything touching a surface the FFmpeg
+patches consume — the **regenerated patch**. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project state
+
+- v0.1.0 scaffold. Landed: `libpelorus` interop ABI + smart-deband flagship
+  (`vf_pelorus_deband_vulkan`, working) + the patch stack against n8.1.1.
+  Stubs/roadmap: temporal denoise, FGS estimation + BSF, optical-flow MV hints,
+  `vf_pelorus_analyze` (measured banding/variance maps).
+- Plan + status: `.workingdir/PLAN.md` and `.workingdir/STATE.md` (local).
+
+## Every commit: keep docs + state in sync
+
+- Update `.workingdir/STATE.md` session log with the commit summary.
+- Update [README.md](README.md) "Landed so far" when a build-order step lands.
+- Update [AGENTS.md](AGENTS.md) layout tree when adding top-level packages.
+- Write a per-subpackage `AGENTS.md` for any new module.
+- Land the ADR + per-surface docs + changelog fragment in the same PR.