research: finalize Zenodo DOI metadata for pilot v1

README.md

@@ -32,10 +32,17 @@ bpfcompat test --artifact ghcr.io/inspektor-gadget/gadget/trace_open:latest --qu
 **Quickstart & trust model:** [docs/quickstart.md](docs/quickstart.md) — gate it in CI
 in ~10 minutes; self-hosted-first, your artifact never leaves your runner.
 
-**Research & citation:** academic-use metadata is in [CITATION.cff](CITATION.cff), and
-the prospective empirical-study protocol lives in [research/](research/README.md).
-The research directory is a protocol/reproducibility scaffold, not a
-peer-reviewed-results claim.
+**Research & citation:** software citation metadata is in [CITATION.cff](CITATION.cff);
+dataset-specific CFF metadata for the frozen pilot is in
+[docs/research-v1/CITATION.cff](docs/research-v1/CITATION.cff), and the
+prospective empirical-study protocol lives in [research/](research/README.md).
+The frozen pilot-v1 dataset is archived on Zenodo with exact-version DOI
+[10.5281/zenodo.22848155](https://doi.org/10.5281/zenodo.22848155); the concept
+DOI for the evolving dataset family is
+[10.5281/zenodo.22848154](https://doi.org/10.5281/zenodo.22848154). Cite the
+version DOI when referring to the exact `research-v1` evidence used for
+reproducibility. The research directory remains an evidence/reproducibility
+scaffold, not a peer-review or institutional-endorsement claim.
 
 **Runs upstream, weekly:** two projects have merged scheduled bpfcompat lanes
 into their own CI.

docs/research-v1-zenodo.md

@@ -1,163 +1,112 @@
-# BPFCompat Research Dataset v1 — Zenodo deposit checklist
+# BPFCompat Research Dataset v1 — Zenodo archival record
 
-This document records the **post-release** DOI workflow for the already-published
-BPFCompat research dataset. It intentionally lives outside `research/**` so the
-frozen `research-v1` archive payload and its committed archive lock remain
-unchanged.
+This document records the **post-release** DOI state for the frozen
+BPFCompat `research-v1` dataset. It intentionally lives outside
+`research/**` so the published v1 archive payload and committed archive lock
+remain unchanged.
 
-## Current publication state
+## Published identifiers
 
 - GitHub tag: `research-v1`
 - tag type: annotated tag
 - tag target commit:
   `141c491bd1508600338e7bc27abbc5a117eb7508`
 - GitHub release: **BPFCompat Research Dataset v1**
 - GitHub release ID: `392145710`
-- published: `2026-09-19T16:58:52Z`
-- DOI: **not yet minted**
-
-The GitHub API does not mark the release object itself immutable. Project policy
-for v1 is therefore **no mutation**: corrections must produce a new research
-version instead of replacing published v1 evidence.
-
-## Release assets
-
-Upload the following release assets to Zenodo without modification.
-
-| File | Size | GitHub SHA-256 |
+- GitHub release publication time: `2026-09-19T16:58:52Z`
+- Zenodo record: `https://zenodo.org/records/22848155`
+- **Version DOI:** `10.5281/zenodo.22848155`
+- **Concept DOI:** `10.5281/zenodo.22848154`
+- Zenodo resource type: Dataset
+- Zenodo version: `research-v1`
+- Zenodo publication date: `2026-09-19`
+- visibility: Public
+- licenses: Apache-2.0 and MIT
+
+Use the **Version DOI** when citing or reproducing the exact pilot-v1 evidence.
+Use the **Concept DOI** only when referring to the evolving BPFCompat research
+dataset family across versions.
+
+## Frozen release assets
+
+The DOI record contains the same four files published by the GitHub
+`research-v1` release.
+
+| File | Size | Canonical SHA-256 |
 | --- | ---: | --- |
 | `archive-manifest.json` | 458,992 B | `6ed6d38d57db57e75964829278a62c7bb4a12cd8fc5db97baebb05a1fdd5e927` |
 | `archive-lock.json` | 1,506 B | `44e0ebe3d32c2c388002a4f44e5d0bf9a476a20ee702c137471a6be89235ddf3` |
 | `bpfcompat-research-v1-payload.zip` | 12,899,271 B | `143a8e8a93e43aebbacfd73465a659ca4cb055db7a576960c9d50ed9bc90a817` |
 | `RELEASE-CHECKSUMS.txt` | 272 B | `bc96087d78bdd8419189b2e51927f3e5c2908dad81155313663af3f29125fdd9` |
 
-The release workflow generated GitHub build-provenance attestations for all four
-files before publishing the release.
-
-### Transfer-integrity gate
+### Integrity evidence
 
-Before uploading anything to Zenodo:
+Before the Zenodo upload, all four downloaded GitHub release assets were
+re-hashed locally with SHA-256 and matched the canonical values above.
 
-1. download all four assets from the published `research-v1` GitHub release;
-2. compute SHA-256 for each downloaded file;
-3. compare every digest against the table above and
-   `RELEASE-CHECKSUMS.txt`;
-4. stop the deposit if any filename, size, or SHA-256 differs.
+After publication, the Zenodo record displayed the expected file sizes and the
+following MD5 values. Those MD5 values were independently reproduced from the
+canonical GitHub archival artifact:
 
-After the Zenodo record is published:
+| File | Canonical / Zenodo MD5 |
+| --- | --- |
+| `archive-manifest.json` | `83c5dced82021323deace2943ff00c72` |
+| `archive-lock.json` | `af401a0eab7cbbe62281c412ceef0261` |
+| `bpfcompat-research-v1-payload.zip` | `ea79cefe6d4a9c2f88448e786bf8dc3d` |
+| `RELEASE-CHECKSUMS.txt` | `f42f8fd12ef2acc398da0e6f0a53368b` |
 
-1. download all four files from the published Zenodo record;
-2. recompute SHA-256 for each file;
-3. compare every digest against the same GitHub release values above;
-4. keep the Zenodo/DOI archival gate open if any post-publication digest differs.
+A strict post-publication Zenodo re-download followed by SHA-256 recomputation
+was not completed in the assistant environment because direct Zenodo file
+downloads were unavailable there. DOI finalization therefore proceeded with
+explicit maintainer acceptance of the stronger pre-upload SHA-256 check plus
+the post-publication exact-size and matching-MD5 evidence above. A later
+independent Zenodo re-download may strengthen the audit trail without changing
+the published v1 record.
 
-The DOI record is considered an exact archival copy of `research-v1` only when
-both the pre-upload and post-publication comparisons pass for all four files.
+## Zenodo metadata
 
-## Recommended Zenodo deposit mode
+- **Resource type:** Dataset
+- **Title:** BPFCompat Research Dataset v1: Empirical eBPF Compatibility Across Linux Vendor Kernels
+- **Creator:** Eren Arı
+- **Publication date:** 2026-09-19
+- **Version:** `research-v1`
+- **Language:** English
+- **Publisher:** Zenodo
+- **Repository URL:** `https://github.com/Kernel-Guard/bpfcompat`
+- **Alternate identifier:** `https://github.com/Kernel-Guard/bpfcompat/releases/tag/research-v1`
+- **Programming languages:** Go, Python
+- **Development status:** Active
+- **Keywords:** eBPF, BPF, Linux kernel, compatibility, vendor kernels, libbpf,
+  BTF, CO-RE, reproducibility, systems research
 
-Use a **manual Zenodo upload** for this research record.
+The Zenodo description intentionally bounds the evidence: the release is a
+reproducibility archive of pilot evidence and is not a claim of peer review,
+population representativeness, institutional approval, or endorsement.
 
-The `research-v1` GitHub release already exists, while Zenodo's GitHub
-integration is intended to ingest releases after a repository is enabled. The
-research object is also primarily a reproducibility dataset/evidence bundle,
-with code included as supporting material.
+## Citation
 
-### Duplicate-record preflight
+For exact `research-v1` reproducibility, cite:
 
-Before creating the manual Zenodo record:
+> Arı, E. (2026). *BPFCompat Research Dataset v1: Empirical eBPF Compatibility
+> Across Linux Vendor Kernels* (Version research-v1) [Dataset]. Zenodo.
+> https://doi.org/10.5281/zenodo.22848155
 
-1. search Zenodo for an existing record matching **BPFCompat Research Dataset
-   v1**, `research-v1`, or the GitHub release URL;
-2. check the Zenodo GitHub integration state for
-   `Kernel-Guard/bpfcompat` and confirm that it has **not** already processed
-   the `research-v1` release;
-3. proceed with the manual deposit only if both checks show that no Zenodo record
-   already represents this release.
+The root `CITATION.cff` remains the frozen BPFCompat **software** citation
+metadata. Dataset-specific machine-readable citation metadata is provided in
+`docs/research-v1/CITATION.cff`, where the Zenodo object is typed as
+**dataset** and bound to the exact Version DOI. This prevents the dataset DOI
+from being misrepresented as the software project's own DOI while preserving
+the frozen v1 archive lock.
 
-If an existing or automatically ingested record is found, do not create a second
-manual record or DOI for the same `research-v1` publication. Reconcile and use
-the existing record instead.
+## No-mutation policy
 
-## Zenodo metadata
+The GitHub API does not mark the release object itself immutable. Project policy
+for v1 is therefore **no mutation**: corrections must produce a new research
+version instead of replacing published v1 evidence.
 
-Recommended values:
+The `research/**` tree is part of the archived v1 payload. Post-release DOI
+bookkeeping must remain outside that frozen payload unless a new research
+version and archive lock are intentionally created.
 
-- **Resource type:** Dataset
-- **Title:** BPFCompat Research Dataset v1: Empirical eBPF Compatibility Across Linux Vendor Kernels
-- **Publication date:** 2026-09-19
-- **Creator:** Eren Arı
-- **Version:** research-v1
-- **Language:** English
-- **Visibility:** Public
-- **Licenses:** Apache-2.0 and MIT
-- **Keywords:**
-  - eBPF
-  - BPF
-  - Linux kernel
-  - compatibility
-  - vendor kernels
-  - libbpf
-  - BTF
-  - CO-RE
-  - reproducibility
-  - systems research
-
-Suggested description:
-
-> BPFCompat Research Dataset v1 is a frozen reproducibility package for an
-> empirical pilot study of compiled eBPF artifact compatibility across Linux
-> vendor kernels and loader paths. The canonical pilot contains 70/70 planned
-> executions: 50 compatible, 13 incompatible, and 7 inconclusive. A bounded
-> post-collection stability sample contains 21/21 same-exact-environment
-> observations with no observed environment drift or same-environment verdict
-> instability. The archive includes normalized evidence, deterministic RQ1–RQ4
-> analysis inputs/outputs, generated paper figures/tables, provenance, exact
-> environment identities, and permitted materialized study inputs.
-> Third-party compiled loader binaries whose complete redistribution notice set
-> was not established are excluded and represented by hashes, source revisions,
-> validation-contract identities, notices, and rebuild provenance. This release
-> is a reproducibility archive of pilot evidence and is not a claim of peer
-> review, population representativeness, institutional approval, or
-> endorsement.
-
-## DOI handling
-
-For the Zenodo DOI field:
-
-1. choose **No** for "Do you already have a DOI for this upload?";
-2. use **Get a DOI now** if the exact version DOI is needed before publication;
-3. do not add the reserved/minted DOI to the frozen `research-v1` release;
-4. after publication, record both:
-   - the **Version DOI** for exact `research-v1` citation;
-   - the **Concept DOI** for the evolving dataset family.
-
-For reproducibility claims and the v1 manuscript, prefer the **Version DOI**.
-
-## Mixed-license note
-
-The archive contains BPFCompat-owned Apache-2.0 material and permitted
-third-party-derived MIT material. File-level provenance, redistribution status,
-and retained notice paths in `archive-manifest.json` are authoritative.
-
-The compiled cilium/ebpf project-loader binary and Falco `scap-open` binary are
-not present in the DOI payload.
-
-## After Zenodo publication
-
-Create a new post-release repository PR, without rewriting the `research-v1`
-tag or GitHub release, that:
-
-1. records the Zenodo record URL, Version DOI, and Concept DOI;
-2. adds the Version DOI to `CITATION.cff`;
-3. adds DOI links to the repository README and research-facing documentation;
-   a target under `research/**` is allowed only after creating a new research
-   version and archive lock;
-4. records that the Zenodo/DOI archival gate is complete;
-5. leaves the GitHub release asset hashes unchanged.
-
-## Frozen-v1 note
-
-The `research/**` tree is part of the archived v1 payload. Post-release
-bookkeeping should therefore remain outside that frozen payload unless a new
-research version and archive lock are intentionally created.
+The `research-v1` tag, GitHub release assets, archive lock, and Zenodo record
+must not be rewritten as part of DOI metadata maintenance.

docs/research-v1/CITATION.cff

@@ -0,0 +1,40 @@
+cff-version: 1.2.0
+message: "If you use the BPFCompat pilot v1 research dataset, please cite this exact Zenodo version."
+title: "BPFCompat Research Dataset v1: Empirical eBPF Compatibility Across Linux Vendor Kernels"
+type: dataset
+authors:
+  - family-names: "Arı"
+    given-names: "Eren"
+doi: "10.5281/zenodo.22848155"
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.22848154"
+    description: "Concept DOI for the evolving BPFCompat research dataset across versions."
+  - type: url
+    value: "https://github.com/Kernel-Guard/bpfcompat/releases/tag/research-v1"
+    description: "GitHub research-v1 release corresponding to this archived dataset."
+version: "research-v1"
+date-released: "2026-09-19"
+repository: "https://zenodo.org/records/22848155"
+url: "https://zenodo.org/records/22848155"
+license:
+  - "Apache-2.0"
+  - "MIT"
+abstract: >-
+  Frozen reproducibility package for an empirical pilot study of compiled eBPF
+  artifact compatibility across Linux vendor kernels and loader paths. The
+  canonical pilot contains 70/70 planned executions: 50 compatible, 13
+  incompatible, and 7 inconclusive. The bounded repeat sample contains 21/21
+  same-exact-environment observations with no observed environment drift or
+  same-environment verdict instability.
+keywords:
+  - eBPF
+  - BPF
+  - Linux kernel
+  - compatibility
+  - vendor kernels
+  - libbpf
+  - BTF
+  - CO-RE
+  - reproducibility
+  - systems research