research: add reproducible LaTeX and arXiv package for pilot v1

.github/workflows/preprint-v1.yml

@@ -0,0 +1,50 @@
+name: preprint-v1
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/preprint-v1.yml"
+      - "docs/paper/latex/**"
+      - "research/paper/generated/figures/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build arXiv preprint package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install TeX and SVG conversion dependencies
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends             inkscape             lmodern             poppler-utils             texlive-fonts-recommended             texlive-latex-base             texlive-latex-extra             texlive-latex-recommended
+
+      - name: Build PDF and minimal arXiv source package
+        run: |
+          set -euo pipefail
+          bash docs/paper/latex/build.sh /tmp/preprint-v1
+
+      - name: Inspect rendered PDF
+        run: |
+          set -euo pipefail
+          pdfinfo /tmp/preprint-v1/bpfcompat-preprint-v1.pdf
+          pages="$(pdfinfo /tmp/preprint-v1/bpfcompat-preprint-v1.pdf | awk '/^Pages:/ {print $2}')"
+          test -n "$pages"
+          test "$pages" -ge 1
+
+      - name: Upload preprint artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: bpfcompat-preprint-v1-${{ github.run_id }}
+          path: |
+            /tmp/preprint-v1/bpfcompat-preprint-v1.pdf
+            /tmp/preprint-v1/bpfcompat-arxiv-v1.tar.gz
+            /tmp/preprint-v1/preprint-v1-SHA256SUMS.txt
+          if-no-files-found: error
+          retention-days: 14

docs/paper/SUBMISSION.md

@@ -34,14 +34,24 @@ This checklist applies to
 
 - [ ] Confirm author display name and affiliation exactly as they should appear.
 - [ ] Add ORCID only if verified by the author.
-- [ ] Convert the Markdown manuscript into the target venue format (LaTeX/PDF).
-- [ ] Convert or embed the three frozen SVG figures without altering their
-      underlying data.
+- [x] Convert the Markdown manuscript into an arXiv-oriented LaTeX/PDF source package.
+- [x] Bind the three frozen SVG figures by SHA-256 and convert them to PDF at build time without altering the empirical data.
 - [ ] Confirm every bibliography entry against its primary publisher/source.
 - [ ] Run spelling/grammar and reference-link checks.
-- [ ] Render the final PDF and visually inspect every figure/table.
-- [ ] Confirm that the final PDF cites the exact Version DOI.
-- [ ] Record the final manuscript SHA-256 before submission.
+- [x] Render the LaTeX PDF locally and visually inspect the title page, tables, figures, and references.
+- [x] Confirm that the final PDF cites the exact Version DOI.
+- [ ] Record the CI-built PDF and arXiv source-package SHA-256 values immediately before external submission.
+
+## Submission-format package
+
+The maintained arXiv-oriented source now lives under `docs/paper/latex/`.
+`build.sh` verifies the frozen figure hashes, converts the exact SVG assets to
+PDF, compiles the manuscript with pdfLaTeX, rejects unresolved references or
+overfull boxes, and produces a minimal upload tarball.
+
+The repository CI workflow `.github/workflows/preprint-v1.yml` independently
+builds the PDF and source package and publishes them as a temporary workflow
+artifact for review.
 
 ## Suggested preprint classification
 

docs/paper/latex/ARXIV.md

@@ -0,0 +1,51 @@
+# arXiv submission metadata — pilot v1
+
+Use this file as the operator checklist when the rendered PDF has been approved.
+
+## Proposed metadata
+
+**Title**
+
+Kernel Version Is Not a Capability Contract: Empirical eBPF Artifact
+Compatibility Across Linux Vendor Kernels
+
+**Author**
+
+Eren Arı
+
+**Primary category**
+
+`cs.OS` is the current proposed primary category because the manuscript is an
+operating-systems compatibility and measurement study. Treat this as a proposed
+classification, not an arXiv acceptance decision.
+
+**Comments**
+
+Preprint. 8 pages, 3 figures. Dataset:
+https://doi.org/10.5281/zenodo.22848155
+
+## Upload source
+
+Upload the generated:
+
+`bpfcompat-arxiv-v1.tar.gz`
+
+Do not upload the entire Git repository. arXiv source files are public, so the
+bundle intentionally excludes Git history, CI logs, intermediate TeX files,
+research raw artifacts, credentials, and unrelated project files.
+
+## Before final submission
+
+- confirm the author name exactly as it should appear;
+- add an affiliation only after confirming its exact public wording;
+- add an ORCID only if verified by the author;
+- inspect the generated PDF page by page;
+- confirm all three figures are legible;
+- confirm the exact Version DOI is present;
+- record the final PDF and source-package SHA-256 values;
+- use arXiv's compilation preview and resolve any TeX warnings/errors before
+  submission.
+
+After an arXiv identifier exists, add it to post-release documentation and, if
+desired, link it as a related work from the Zenodo record. Do not rewrite the
+frozen pilot-v1 dataset.

docs/paper/latex/README.md

@@ -0,0 +1,71 @@
+# Pilot v1 LaTeX / arXiv package
+
+This directory contains the submission-format source for the BPFCompat pilot-v1
+preprint. It is intentionally outside `research/**`, because the archived
+`research-v1` evidence payload is frozen.
+
+## Build
+
+Required local tools:
+
+- `pdflatex`
+- `inkscape`
+- `sha256sum`
+- `tar`
+
+From the repository root:
+
+```bash
+bash docs/paper/latex/build.sh
+```
+
+Outputs are written to `docs/paper/latex/build/`:
+
+- `bpfcompat-preprint-v1.pdf` — rendered review PDF;
+- `bpfcompat-arxiv-v1.tar.gz` — minimal source package for upload;
+- `preprint-v1-SHA256SUMS.txt` — source/figure/package checksums.
+
+The arXiv package contains only:
+
+```text
+main.tex
+figures/figure-1.pdf
+figures/figure-2.pdf
+figures/figure-3.pdf
+```
+
+The bibliography is embedded in `main.tex`, so no BibTeX/Biber step is
+required.
+
+## Frozen figure binding
+
+The build fails unless the three source SVGs still match the SHA-256 values in
+the frozen pilot-v1 paper asset manifest. It then converts those exact SVGs to
+PDF for pdfLaTeX.
+
+Ubuntu 24.04 currently ships Inkscape 1.2, which can omit SVG2
+`<use href="#...">` instances during PDF conversion. The build therefore
+creates a temporary conversion-only copy that rewrites that SVG presentation
+syntax to the equivalent `xlink:href` form. The frozen source SVGs remain
+untouched and hash-verified; Figure 3 also requires all 70 matrix-cell
+`<use>` instances to survive this normalization.
+
+The manuscript cites the exact dataset Version DOI:
+
+`10.5281/zenodo.22848155`
+
+Do not replace it with the Concept DOI when referring to the exact evidence used
+by this manuscript.
+
+## Evidence boundary
+
+The LaTeX package is publication formatting, not a new dataset version. Editing
+this directory must not change:
+
+- `research/**`;
+- the `research-v1` tag or GitHub release;
+- the Zenodo dataset files;
+- archive locks or frozen generated analysis.
+
+If an empirical claim changes, create a new research dataset version rather than
+silently updating pilot-v1 evidence.

docs/paper/latex/build.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(git rev-parse --show-toplevel)"
+src="$root/docs/paper/latex/main.tex"
+frozen="$root/research/paper/generated/figures"
+out="${1:-$root/docs/paper/latex/build}"
+pkg="$out/arxiv-v1"
+
+for cmd in sha256sum inkscape pdflatex tar; do
+  command -v "$cmd" >/dev/null 2>&1 || {
+    echo "[preprint-v1] missing required command: $cmd" >&2
+    exit 1
+  }
+done
+
+expected_fig1="e603453187145edb3400bcdb486e179d76d7657a38b02d0619a7d2eb950cad43"
+expected_fig2="7fad1b1fa74d42d0cd6e8b870acfe2e200314d63a691f66186d3cb854e6d80f9"
+expected_fig3="1c3c8e9f043612e3b55b3f128a12fd5ca7c967ebbdfd4c66a2dd98c2ea49a509"
+
+check_sha() {
+  local file="$1"
+  local expected="$2"
+  local got
+  got="$(sha256sum "$file" | awk '{print $1}')"
+  [[ "$got" == "$expected" ]] || {
+    echo "[preprint-v1] frozen figure hash mismatch: $file" >&2
+    echo "expected=$expected" >&2
+    echo "got=$got" >&2
+    exit 1
+  }
+}
+
+check_sha "$frozen/figure-1-study-architecture.svg" "$expected_fig1"
+check_sha "$frozen/figure-2-ringbuf-version.svg" "$expected_fig2"
+check_sha "$frozen/figure-3-compatibility-matrix.svg" "$expected_fig3"
+
+grep -Fq '10.5281/zenodo.22848155' "$src" || {
+  echo "[preprint-v1] exact Version DOI missing from main.tex" >&2
+  exit 1
+}
+
+rm -rf "$out"
+mkdir -p "$pkg/figures" "$out/svg-compat"
+cp "$src" "$pkg/main.tex"
+
+normalize_svg_use_href() {
+  local src_svg="$1"
+  local dst_svg="$2"
+  python3 - "$src_svg" "$dst_svg" <<'PY'
+from pathlib import Path
+import sys
+
+src = Path(sys.argv[1])
+dst = Path(sys.argv[2])
+text = src.read_text(encoding="utf-8")
+
+# Inkscape 1.2 on Ubuntu 24.04 drops SVG2 <use href="#..."> instances.
+# Normalize only that presentation syntax for conversion; the frozen source SVG
+# remains hash-verified and untouched.
+if '<use href=' in text:
+    if 'xmlns:xlink=' not in text:
+        text = text.replace(
+            '<svg xmlns="http://www.w3.org/2000/svg"',
+            '<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"',
+            1,
+        )
+    text = text.replace('<use href=', '<use xlink:href=')
+
+dst.write_text(text, encoding="utf-8")
+PY
+}
+
+convert_svg() {
+  local src_svg="$1"
+  local compat_svg="$2"
+  local dst_pdf="$3"
+  normalize_svg_use_href "$src_svg" "$compat_svg"
+  inkscape "$compat_svg" --export-type=pdf --export-filename="$dst_pdf"
+}
+
+convert_svg \
+  "$frozen/figure-1-study-architecture.svg" \
+  "$out/svg-compat/figure-1.svg" \
+  "$pkg/figures/figure-1.pdf"
+convert_svg \
+  "$frozen/figure-2-ringbuf-version.svg" \
+  "$out/svg-compat/figure-2.svg" \
+  "$pkg/figures/figure-2.pdf"
+convert_svg \
+  "$frozen/figure-3-compatibility-matrix.svg" \
+  "$out/svg-compat/figure-3.svg" \
+  "$pkg/figures/figure-3.pdf"
+
+# Figure 3 has 70 matrix cells represented by <use> instances. Ensure the
+# compatibility normalization preserved all of them before LaTeX compilation.
+test "$(grep -o 'xlink:href=' "$out/svg-compat/figure-3.svg" | wc -l)" -eq 70
+
+(
+  cd "$pkg"
+  pdflatex -interaction=nonstopmode -halt-on-error main.tex >/tmp/bpfcompat-preprint-v1-pass1.log
+  pdflatex -interaction=nonstopmode -halt-on-error main.tex >/tmp/bpfcompat-preprint-v1-pass2.log
+
+  if grep -Eq 'Undefined references|Citation .* undefined|Overfull \\hbox' main.log; then
+    echo "[preprint-v1] LaTeX quality gate failed" >&2
+    grep -E 'Undefined references|Citation .* undefined|Overfull \\hbox' main.log >&2 || true
+    exit 1
+  fi
+
+  rm -f main.aux main.log main.out main.toc main.fls main.fdb_latexmk
+)
+
+cp "$pkg/main.pdf" "$out/bpfcompat-preprint-v1.pdf"
+
+(
+  cd "$pkg"
+  sha256sum main.tex figures/figure-1.pdf figures/figure-2.pdf figures/figure-3.pdf \
+    > "$out/preprint-v1-SHA256SUMS.txt"
+)
+
+tar --sort=name \
+  --mtime='UTC 2026-09-19' \
+  --owner=0 --group=0 --numeric-owner \
+  -czf "$out/bpfcompat-arxiv-v1.tar.gz" \
+  -C "$pkg" main.tex figures
+
+sha256sum \
+  "$out/bpfcompat-preprint-v1.pdf" \
+  "$out/bpfcompat-arxiv-v1.tar.gz" \
+  >> "$out/preprint-v1-SHA256SUMS.txt"
+
+echo "[preprint-v1] built:"
+echo "  $out/bpfcompat-preprint-v1.pdf"
+echo "  $out/bpfcompat-arxiv-v1.tar.gz"
+echo "  $out/preprint-v1-SHA256SUMS.txt"