build(node): generate the eBPF object at build time with a pinned clang instead of committing it (ADR-1622)

[lusoris]

Summary

The node's eBPF object is now generated at build time with a pinned clang instead of being committed, which removes the ELF that Scorecard's Binary-Artifacts check flags (the maintainer decided this on 2026-10-05). scripts/dev/gen-node-bpf.sh (make node-bpf) is the single generation step; Go CI, docker/Dockerfile.node, dev/Containerfile and the go-build / go-test targets call it. build-config.env pins clang 19.1.7 and the object's sha256; --require-pin refuses anything else, and a missing tool fails naming it, with no fallback and no download.

Stacked on #2061 (it carries the T-SCORECARD-COMMITTED-BPF-OBJECT-2026-10-05 row this PR closes).

The bpf2go binding stays committed source, with its go:embed rewritten to embeddedObject(). The locked Go API Compatibility gate runs go list -export ./... with no generation step, so the package has to compile without the object. A node built without it refuses VMAFX_EBPF_BYPASS=1 and names the generator.

Type

• build / ci — tooling / infra

Checklist

• Commits follow Conventional Commits.
• make format && make lint is green locally (commit hooks passed).
• Unit tests: not a libvmaf change; go test ./cmd/vmafx-node/... and scripts/dev/tests/test_gen_node_bpf.py pass.
• No SIMD/GPU code path touched.
• No feature extractor touched.
• No new C / C++ source; the new Go and shell files carry the licence header.
• Not a breaking change for users; contributors need clang to produce the object (migration below).
• ADR-1622 row lives in docs/adr/_index_fragments/1622-bpf-object-generated-at-build-time.md, slug appended to _order.txt.

Bug-status hygiene

• docs/state.md: T-SCORECARD-COMMITTED-BPF-OBJECT-2026-10-05 moved from Open to Recently closed with the evidence.

Netflix golden-data gate

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

Deep-dive deliverables

• Research digest — no digest needed: the measurements are in the ADR and the state row.
• Decision matrix — in ADR-1622 ## Alternatives considered.
• AGENTS.md invariant note — cmd/vmafx-node/AGENTS.md item 15.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/changed/node-ebpf-object-generated-at-build-time.md.
• Rebase note — docs/rebase-notes.md, "The node's eBPF object is generated at build time".

Reproducer

make node-bpf BPF_PIN=--require-pin   # needs clang 19.1.7; without clang it fails naming it
go test ./cmd/vmafx-node/...
python3 -m pytest scripts/dev/tests/test_gen_node_bpf.py
docker build -f docker/Dockerfile.node --target go-builder .

Measured:

• clang 19.1.7 builds a8079aa4e539dc30e5f275a424f1831d911fb0ef72e579c5c8527b8de2415ca0 on Debian 13 amd64, Debian 13 arm64 (QEMU) and Ubuntu 26.04 amd64; clang 23.1.1 reproduces the previously committed object byte for byte.
• docker build --target go-builder of Dockerfile.node from a tree without the object: gen-node-bpf --require-pin passes inside the stage and go build produces /out/vmafx-node.
• With the pinned clang in a golang:1.27-trixie container, TestEmbeddedObjectMatchesPinnedDigest, TestEmbeddedObjectMatchesMirrors and TestEmbeddedObjectLicence pass; without the object the package builds and those tests skip naming make node-bpf.
• With PATH lacking clang, make node-bpf exits 2: clang not found ... install clang 19.1.7 ... apt-get install clang-19 llvm-19 libbpf-dev.
• go test ./cmd/vmafx-node/... passes against the in-tree CPU libvmaf (VMAF_BIN set to the CPU vmaf).

Known follow-ups

• Not verified: Binary-Artifacts reading 10 on the next Scorecard run on master.
• dev/Containerfile was edited (clang-19 neighbours, llvm-19, libbpf-dev, the generation step) but its full image was not built here; the same script, packages and digest were exercised in the Debian and Ubuntu containers.
• core/test/fuzz/**/*.bin are the only other .bin files in the tree; they are ASCII text and data, not executables.

Breaking changes / migration

Producing the node's eBPF object needs clang with the BPF target, llvm-strip and the libbpf headers: run make node-bpf (see docs/development/node-ebpf-build.md). Container builds need nothing on the host.