bench.yml

# yamllint disable rule:line-length

name: bench

# yamllint disable rule:truthy
on:
  # Only fire on PRs that actually target an integration branch. Stacked
  # feature-to-feature PRs (`feat/foo` -> `feat/bar`) used to be in this
  # allowlist; they have been removed because cascade-rebases would
  # otherwise burn Bencher quota uploading near-identical reports for
  # every intermediate stack PR. The topmost PR (base=devel) still gets
  # PR-time bench treatment, gated further by the `bench` label below.
  pull_request:
    branches: [main, devel]
    paths-ignore:
      - '*.md'
      - '.github/workflows/docs.yml'
      # Loop-prevention layer 1 of 3 (design §5.X): the snapshot push
      # writes BMF JSON under docs/assets/bench-results/. paths-ignore
      # makes the bench job skip any push consisting solely of these
      # snapshot files, so the snapshot commit cannot retrigger bench.
      # Companion guards are (2) the bot-actor `if:` on the matrix and
      # bench-upload jobs below, and (3) `[skip ci]` in the snapshot
      # and defensive-fallback commit messages (added v4.2.0 thread
      # D1) to suppress recursive triggers under workflow_dispatch
      # re-runs and any future paths-ignore loosening. docs.yml's
      # chart deploy is acceptable to defer because the next non-bot
      # push to devel rebuilds and redeploys the docs site.
      - 'docs/assets/bench-results/**'
  push:
    branches: [main, devel]
    paths-ignore:
      - '*.md'
      - '.github/workflows/docs.yml'
      - 'docs/assets/bench-results/**'
  workflow_dispatch:
    inputs:
      force_skip_boost:
        description: 'Force boost soft-skip (Track 3 §2.6 acceptance)'
        type: boolean
        default: false
      force_skip_loony:
        description: 'Force loony soft-skip (Track 3 §2.6 acceptance)'
        type: boolean
        default: false
      force_skip_moodycamel:
        description: 'Force MoodyCamel soft-skip (Track 4 §4.7 acceptance)'
        type: boolean
        default: false
      force_skip_threading_channels:
        description: 'Force threading.Chan soft-skip (Track 4 §4.7 acceptance)'
        type: boolean
        default: false
      force_skip_nim_channel:
        description: 'Force system.Channel soft-skip (Track 4 §4.7 acceptance)'
        type: boolean
        default: false
# yamllint enable rule:truthy

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  # Exposed at job env so step-level `if:` expressions can gate on
  # presence via `env.BENCHER_API_TOKEN`. GitHub Actions does not allow
  # `secrets.*` directly in `if:`, so the env-var indirection is required.
  BENCHER_API_TOKEN: ${{ secrets.BENCHER_API_TOKEN }}
  # Track 3 §2.6 + Track 4 §4.7 soft-skip overrides. Empty string when
  # the workflow_dispatch input is unset (the default), '1' when the
  # operator forces a skip. Step-level `if:` clauses gate on these.
  FORCE_SKIP_BOOST: ${{ inputs.force_skip_boost && '1' || '' }}
  FORCE_SKIP_LOONY: ${{ inputs.force_skip_loony && '1' || '' }}
  FORCE_SKIP_MOODYCAMEL: ${{ inputs.force_skip_moodycamel && '1' || '' }}
  FORCE_SKIP_THREADING_CHANNELS: ${{ inputs.force_skip_threading_channels && '1' || '' }}
  FORCE_SKIP_NIM_CHANNEL: ${{ inputs.force_skip_nim_channel && '1' || '' }}

jobs:
  bench-tests:
    # Compiles and runs `tests/t_bench_*.nim` (the bench harness's own
    # unit tests: t_bench_common, t_bench_latency, t_bench_adapters).
    # These tests live outside `srcDir` and are intentionally NOT
    # imported by tests/test.nim (see lockfreequeues.nimble) so the
    # regular `nimble test` matrix (8 invocations across MM/sanitizer
    # combos) does not pull in the bench harness's threading/atomic
    # dependencies. Without this job the HistogramTopK / latency CLI /
    # adapter assertions are never enforced in CI.
    #
    # No secret dependencies: fork PRs are allowed so contributors get
    # the same harness validation as maintainer pushes. The bot-actor
    # guard prevents loop-back from the bench-snapshot push commit
    # (see docs.yml). Sibling Nim deps are pinned to release tags
    # (not `main`) for deterministic CI; bump in lockstep with
    # build.yml/bench.yml's `benchmark` job and lockfreequeues.nimble's
    # `requires`.
    name: bench-tests (ubuntu-latest)
    runs-on: ubuntu-latest
    if: github.actor != 'github-actions[bot]'
    timeout-minutes: 10

    steps:
      - name: Checkout project
        uses: actions/checkout@v4

      - name: Setup Nim
        uses: jiro4989/setup-nim-action@v2
        with:
          nim-version: 'stable'

      - name: Install build deps (Linux)
        run: |
          sudo apt-get update -q -y
          sudo apt-get -qq install -y clang

      - name: Clone and install sibling Nim deps (nim-debra, nim-typestates)
        run: |
          set -e
          cd ..
          git clone --depth 1 --branch main https://github.com/elijahr/nim-debra.git
          git clone --depth 1 --branch main https://github.com/elijahr/nim-typestates.git
          (cd nim-typestates && nimble install -y)
          (cd nim-debra && nimble install -y)

      - name: Vendor unittest2
        run: git clone --depth 1 https://github.com/status-im/nim-unittest2.git deps/unittest2

      - name: Run bench harness tests
        run: nimble benchtests

  bench:
    # Track 2 PR 2: matrix over the 5 topology-split binaries. Each
    # matrix entry is its own GitHub Actions job with an independent
    # `timeout-minutes: 18` budget so a hang in one binary cannot burn
    # the entire workflow's clock — the surviving binaries finish, the
    # bench-upload job merges what arrived, and the operator gets
    # partial Bencher coverage rather than no coverage. Per-binary
    # `-d:` overrides are tuned to fit each variant's CI budget; see
    # design 2.5 for the override table.
    name: ${{ matrix.binary }} (ubuntu-latest)
    runs-on: ubuntu-latest
    # Two combined gates:
    #   1. PRs from forks cannot read BENCHER_API_TOKEN. Skip rather
    #      than fail noisily; maintainer pushes / merges still record
    #      the baseline.
    #   2. Loop-prevention layer 2 of 2 (design §5.X): the snapshot
    #      push step (Task 5.5.b) commits as `github-actions[bot]`.
    #      Even if paths-ignore is ever loosened, the bot-actor guard
    #      short-circuits before the job grows any cost.
    if: |
      github.actor != 'github-actions[bot]' &&
      (github.event_name != 'pull_request' ||
       github.event.pull_request.head.repo.full_name == github.repository)
    strategy:
      fail-fast: false
      matrix:
        binary:
          - bench_spsc
          - bench_mpsc
          - bench_mpmc
          - bench_unbounded
          - bench_latency
    timeout-minutes: 18

    steps:
      - name: Restore cache
        uses: actions/cache@v4
        with:
          path: ${HOME}/.cache
          key: cache-${{ matrix.binary }}-${{ runner.os }}

      - name: Checkout project
        uses: actions/checkout@v4

      - name: Setup Nim
        uses: jiro4989/setup-nim-action@v2
        with:
          nim-version: 'stable'

      - name: Install build deps (Linux)
        run: |
          sudo apt-get update -q -y
          sudo apt-get -qq install -y clang

      - name: Clone and install sibling Nim deps (nim-debra, nim-typestates)
        # Mirrors build.yml: nim.cfg uses --path:"../nim-debra/src" and
        # --path:"../nim-typestates/src", and nimble's resolver runs before
        # the compiler so we must install matching branches locally. Tracks
        # `main` until nimble.directory picks up the relevant tags; bump in
        # lockstep with build.yml and lockfreequeues.nimble's `requires`.
        run: |
          set -e
          cd ..
          git clone --depth 1 --branch main https://github.com/elijahr/nim-debra.git
          git clone --depth 1 --branch main https://github.com/elijahr/nim-typestates.git
          (cd nim-typestates && nimble install -y)
          (cd nim-debra && nimble install -y)

      - name: Vendor unittest2
        run: git clone --depth 1 https://github.com/status-im/nim-unittest2.git deps/unittest2

      # ---------- Track 3 MVP adapter installs (soft-skip) ----------
      #
      # Each adapter has three stages: install -> smoke -> set-env-on-success.
      # Failure at any stage flips the binary's compile flags so the slugs
      # are simply omitted from the BMF instead of failing the workflow.
      # Annotate-skipped steps surface a yellow PR-check warning.

      - name: Install boost (libboost-dev for Boost.LockFree)
        # Boost.LockFree is C++ header-only; libboost-dev pulls the
        # entire boost include tree on the runner. Skip on bench_mpsc /
        # bench_unbounded / bench_latency (no boost adapter wired into
        # those binaries; install would just slow them down).
        id: install-boost
        if: |
          env.FORCE_SKIP_BOOST != '1' &&
          (matrix.binary == 'bench_spsc' || matrix.binary == 'bench_mpmc')
        continue-on-error: true
        run: |
          sudo apt-get install -qq -y libboost-dev

      - name: Smoke boost adapters
        id: smoke-boost
        if: |
          env.FORCE_SKIP_BOOST != '1' &&
          steps.install-boost.outcome == 'success' &&
          (matrix.binary == 'bench_spsc' || matrix.binary == 'bench_mpmc')
        continue-on-error: true
        run: |
          set -eu
          # Compile and run the smoke binary with both gates so a single
          # invocation covers queue + spsc_queue. nim cpp because boost
          # headers are C++.
          nim cpp -d:release -d:danger --threads:on \
            -d:adapter_boost_lockfree_queue_available \
            -d:adapter_boost_lockfree_spsc_available \
            -o:.tmp/smoke_boost \
            benchmarks/nim/smoke/smoke_boost.nim
          ./.tmp/smoke_boost

      - name: Set boost adapter defines (success only)
        if: |
          env.FORCE_SKIP_BOOST != '1' &&
          steps.install-boost.outcome == 'success' &&
          steps.smoke-boost.outcome == 'success'
        run: |
          {
            echo "ADAPTER_BOOST_QUEUE=1"
            echo "ADAPTER_BOOST_SPSC=1"
          } >> "$GITHUB_ENV"

      - name: Annotate boost skipped
        if: |
          (matrix.binary == 'bench_spsc' || matrix.binary == 'bench_mpmc') &&
          (env.FORCE_SKIP_BOOST == '1' ||
           steps.install-boost.outcome != 'success' ||
           steps.smoke-boost.outcome != 'success')
        run: |
          echo "::warning title=Adapter skipped::boost.lockfree install or smoke failed for ${{ matrix.binary }}; bench will omit boost slugs."

      - name: Install loony (nimble)
        # Loony is a Nim-only unbounded MPMC queue; nimble pulls it from
        # the registry. Only bench_unbounded uses it.
        id: install-loony
        if: |
          env.FORCE_SKIP_LOONY != '1' &&
          matrix.binary == 'bench_unbounded'
        continue-on-error: true
        run: |
          nimble install -y loony

      - name: Smoke loony adapter
        id: smoke-loony
        if: |
          env.FORCE_SKIP_LOONY != '1' &&
          steps.install-loony.outcome == 'success' &&
          matrix.binary == 'bench_unbounded'
        continue-on-error: true
        run: |
          # The smoke is the round-trip test in tests/t_bench_adapters.nim.
          # Compile-only; runs in <1s.
          set -eu
          nim c -d:release -d:danger --threads:on \
            -d:adapter_loony_available \
            -o:.tmp/smoke_loony \
            -r tests/t_bench_adapters.nim

      - name: Set loony adapter define (success only)
        if: |
          env.FORCE_SKIP_LOONY != '1' &&
          steps.install-loony.outcome == 'success' &&
          steps.smoke-loony.outcome == 'success'
        run: echo "ADAPTER_LOONY=1" >> "$GITHUB_ENV"

      - name: Annotate loony skipped
        if: |
          matrix.binary == 'bench_unbounded' &&
          (env.FORCE_SKIP_LOONY == '1' ||
           steps.install-loony.outcome != 'success' ||
           steps.smoke-loony.outcome != 'success')
        run: |
          echo "::warning title=Adapter skipped::loony install or smoke failed; bench will omit loony slugs."

      # ---------- Track 4 PR-4 adapter installs (soft-skip) ----------
      #
      # MoodyCamel: vendored single-header at
      # benchmarks/vendor/concurrentqueue/concurrentqueue.h. The
      # "install" step is therefore a `test -f` rather than a fetch, so
      # the bench is reproducible without network egress. Only
      # bench_unbounded wires the moodycamel adapter (mpmc_unbounded).
      - name: Install MoodyCamel (vendored header presence check)
        id: install-moodycamel
        if: |
          env.FORCE_SKIP_MOODYCAMEL != '1' &&
          matrix.binary == 'bench_unbounded'
        continue-on-error: true
        run: |
          test -f benchmarks/vendor/concurrentqueue/concurrentqueue.h
          test -f benchmarks/vendor/concurrentqueue/moodycamel_wrapper.cpp

      - name: Smoke MoodyCamel adapter
        id: smoke-moodycamel
        if: |
          env.FORCE_SKIP_MOODYCAMEL != '1' &&
          steps.install-moodycamel.outcome == 'success' &&
          matrix.binary == 'bench_unbounded'
        continue-on-error: true
        run: |
          set -eu
          # nim cpp because concurrentqueue.h is C++ and the wrapper
          # is C++ source compiled in via `{.compile: ...}`.
          nim cpp -d:release -d:danger --threads:on \
            -d:adapter_moodycamel_available \
            -o:.tmp/smoke_moodycamel \
            benchmarks/nim/smoke/smoke_moodycamel.nim
          ./.tmp/smoke_moodycamel

      - name: Set MoodyCamel adapter define (success only)
        if: |
          env.FORCE_SKIP_MOODYCAMEL != '1' &&
          steps.install-moodycamel.outcome == 'success' &&
          steps.smoke-moodycamel.outcome == 'success'
        run: echo "ADAPTER_MOODYCAMEL=1" >> "$GITHUB_ENV"

      - name: Annotate MoodyCamel skipped
        if: |
          matrix.binary == 'bench_unbounded' &&
          (env.FORCE_SKIP_MOODYCAMEL == '1' ||
           steps.install-moodycamel.outcome != 'success' ||
           steps.smoke-moodycamel.outcome != 'success')
        run: |
          echo "::warning title=Adapter skipped::moodycamel install or smoke failed; bench will omit moodycamel slugs."

      # threading.Chan (nimble package): only used by bench_mpmc.
      - name: Install threading (nimble)
        id: install-threading-channels
        if: |
          env.FORCE_SKIP_THREADING_CHANNELS != '1' &&
          matrix.binary == 'bench_mpmc'
        continue-on-error: true
        run: |
          nimble install -y threading

      - name: Smoke threading.Chan adapter
        id: smoke-threading-channels
        if: |
          env.FORCE_SKIP_THREADING_CHANNELS != '1' &&
          steps.install-threading-channels.outcome == 'success' &&
          matrix.binary == 'bench_mpmc'
        continue-on-error: true
        run: |
          set -eu
          nim c -d:release -d:danger --threads:on \
            -d:adapter_threading_channels_available \
            -o:.tmp/smoke_threading_channels \
            benchmarks/nim/smoke/smoke_threading_channels.nim
          ./.tmp/smoke_threading_channels

      - name: Set threading.Chan adapter define (success only)
        if: |
          env.FORCE_SKIP_THREADING_CHANNELS != '1' &&
          steps.install-threading-channels.outcome == 'success' &&
          steps.smoke-threading-channels.outcome == 'success'
        run: echo "ADAPTER_THREADING_CHANNELS=1" >> "$GITHUB_ENV"

      - name: Annotate threading.Chan skipped
        if: |
          matrix.binary == 'bench_mpmc' &&
          (env.FORCE_SKIP_THREADING_CHANNELS == '1' ||
           steps.install-threading-channels.outcome != 'success' ||
           steps.smoke-threading-channels.outcome != 'success')
        run: |
          echo "::warning title=Adapter skipped::threading.Chan install or smoke failed; bench will omit threading_channels slugs."

      # system.Channel (Nim stdlib, no install): only used by bench_mpsc.
      # The "install" step is a no-op success placeholder so the
      # FORCE_SKIP_NIM_CHANNEL flag has the same shape as the other
      # adapters; the real check happens in the smoke step.
      - name: Smoke system.Channel adapter
        id: smoke-nim-channel
        if: |
          env.FORCE_SKIP_NIM_CHANNEL != '1' &&
          matrix.binary == 'bench_mpsc'
        continue-on-error: true
        run: |
          set -eu
          # The smoke is the round-trip test in tests/t_bench_adapters.nim
          # under the nim_channel gate; the default Nim install ships
          # system.Channel so no install step is required.
          nim c -d:release -d:danger --threads:on \
            -d:adapter_nim_channel_available \
            -o:.tmp/smoke_nim_channel \
            -r tests/t_bench_adapters.nim

      - name: Set system.Channel adapter define (success only)
        if: |
          env.FORCE_SKIP_NIM_CHANNEL != '1' &&
          steps.smoke-nim-channel.outcome == 'success'
        run: echo "ADAPTER_NIM_CHANNEL=1" >> "$GITHUB_ENV"

      - name: Annotate system.Channel skipped
        if: |
          matrix.binary == 'bench_mpsc' &&
          (env.FORCE_SKIP_NIM_CHANNEL == '1' ||
           steps.smoke-nim-channel.outcome != 'success')
        run: |
          echo "::warning title=Adapter skipped::system.Channel smoke failed; bench will omit nim_channel slugs."

      - name: Build adapter define flags
        # Aggregates the per-adapter env flags into a single shell
        # variable consumed by the compile step. Empty when no adapter
        # is enabled; properly space-separated otherwise.
        id: adapter-flags
        run: |
          set -eu
          flags=""
          mode="c"
          if [ "${ADAPTER_BOOST_QUEUE:-}" = "1" ]; then
            flags="$flags -d:adapter_boost_lockfree_queue_available"
            mode="cpp"
          fi
          if [ "${ADAPTER_BOOST_SPSC:-}" = "1" ]; then
            flags="$flags -d:adapter_boost_lockfree_spsc_available"
            mode="cpp"
          fi
          if [ "${ADAPTER_LOONY:-}" = "1" ]; then
            flags="$flags -d:adapter_loony_available"
          fi
          if [ "${ADAPTER_MOODYCAMEL:-}" = "1" ]; then
            flags="$flags -d:adapter_moodycamel_available"
            mode="cpp"
          fi
          if [ "${ADAPTER_THREADING_CHANNELS:-}" = "1" ]; then
            flags="$flags -d:adapter_threading_channels_available"
          fi
          if [ "${ADAPTER_NIM_CHANNEL:-}" = "1" ]; then
            flags="$flags -d:adapter_nim_channel_available"
          fi
          {
            echo "flags=$flags"
            echo "mode=$mode"
          } >> "$GITHUB_OUTPUT"
          echo "Adapter flags: $flags"
          echo "Compile mode:  $mode"

      - name: Compile ${{ matrix.binary }} (CI-tuned run shape)
        # Per-binary -d: overrides mirror the design 2.5 CI override
        # column. Bounded throughput binaries: 1M messages × 5 runs ×
        # 2 warmup; cheap, single-digit seconds total. bench_unbounded
        # uses a tighter shape — sipsic 200K×3, sipmuc/mupsic 100K×2,
        # mupmuc 50K×2 — because the 16-shape total (1+3+3+9) plus
        # oversubscribed shapes like 1p4c on 4-vCPU runners exhausts
        # the budget at higher N. The mupmuc 9-shape grid dominates
        # the wall clock so it gets the deepest cut. bench_latency
        # keeps PR 1's tighter shape (50K × 11 × 2) because each
        # ping-pong RTT records exactly one sample, so 1M messages
        # would never fit.
        #
        # ${{ steps.adapter-flags.outputs.flags }} is the space-separated
        # set of -d:adapter_*_available defines that survived install +
        # smoke. ${{ steps.adapter-flags.outputs.mode }} is 'cpp' iff at
        # least one C++-only adapter (boost) is enabled, else 'c'.
        env:
          NIM_MODE: ${{ steps.adapter-flags.outputs.mode }}
          ADAPTER_FLAGS: ${{ steps.adapter-flags.outputs.flags }}
        run: |
          set -eu
          # shellcheck disable=SC2086  # ADAPTER_FLAGS is intentionally word-split.
          case "${{ matrix.binary }}" in
            bench_spsc)
              nim "$NIM_MODE" -d:release -d:danger --threads:on \
                -d:BenchSpscMessageCount=1000000 \
                -d:BenchSpscRuns=5 \
                -d:BenchSpscWarmup=2 \
                $ADAPTER_FLAGS \
                benchmarks/nim/bench_spsc.nim
              ;;
            bench_mpsc)
              # PR 4 wires nim_channel (Nim stdlib, plain `nim c`) into
              # bench_mpsc. No C++-only adapters live here, so ignore
              # NIM_MODE and stay on `nim c`; ADAPTER_FLAGS may carry
              # -d:adapter_nim_channel_available.
              nim c -d:release -d:danger --threads:on \
                -d:BenchMpscMessageCount=1000000 \
                -d:BenchMpscRuns=5 \
                -d:BenchMpscWarmup=2 \
                $ADAPTER_FLAGS \
                benchmarks/nim/bench_mpsc.nim
              ;;
            bench_mpmc)
              nim "$NIM_MODE" -d:release -d:danger --threads:on \
                -d:BenchMpmcMessageCount=1000000 \
                -d:BenchMpmcRuns=5 \
                -d:BenchMpmcWarmup=2 \
                $ADAPTER_FLAGS \
                benchmarks/nim/bench_mpmc.nim
              ;;
            bench_unbounded)
              # bench_unbounded supports loony (Nim, plain `nim c`) and
              # PR 4's MoodyCamel (C++ vendored header, requires `nim
              # cpp`). NIM_MODE is "cpp" iff ADAPTER_MOODYCAMEL was
              # set; otherwise it stays "c". loony is mode-neutral.
              nim "$NIM_MODE" -d:release -d:danger --threads:on \
                -d:UnboundedSipsicMessageCount=200000 \
                -d:UnboundedSipsicRuns=3 \
                -d:UnboundedSipmucMessageCount=100000 \
                -d:UnboundedSipmucRuns=2 \
                -d:UnboundedMupsicMessageCount=100000 \
                -d:UnboundedMupsicRuns=2 \
                -d:UnboundedMupmucMessageCount=50000 \
                -d:UnboundedMupmucRuns=2 \
                -d:BenchUnboundedWarmup=1 \
                -d:BenchSkipOversubscribed \
                $ADAPTER_FLAGS \
                benchmarks/nim/bench_unbounded.nim
              ;;
            bench_latency)
              nim c -d:release -d:danger --threads:on \
                -d:BenchLatencyMessageCount=50000 \
                -d:BenchLatencyRuns=11 \
                -d:BenchLatencyWarmupRuns=2 \
                benchmarks/nim/bench_latency.nim
              ;;
            *)
              echo "::error::unknown binary: ${{ matrix.binary }}"
              exit 1
              ;;
          esac

      - name: Run ${{ matrix.binary }}
        # Step-level timeout: a runtime hang in one variant (lost
        # message, missed wakeup, livelock regression) would otherwise
        # spin until the job-level 18-min budget expired. Fail fast at
        # 10 min so the upload step still records the partial result.
        timeout-minutes: 10
        run: |
          ./.tmp/${{ matrix.binary }} --bmf-out=${{ matrix.binary }}.json \
            | tee ${{ matrix.binary }}_output.txt

      - name: Upload ${{ matrix.binary }} BMF artifact
        # `if: always()` so a step-level timeout in `Run ${{ matrix.binary }}`
        # still uploads any partial JSON the binary managed to flush;
        # `if-no-files-found: ignore` so a binary that crashed before
        # writing the file does not turn the whole job red — the
        # bench-upload job merges whatever artifacts arrive and the
        # operator gets partial coverage rather than zero coverage.
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: bench-${{ matrix.binary }}-bmf
          path: ${{ matrix.binary }}.json
          if-no-files-found: ignore

  bench-upload:
    # Merges per-binary BMF artifacts into a single JSON before a single
    # `bencher run` invocation. Bencher creates a separate Report per
    # invocation; multiple uploads would NOT co-locate measures on a
    # single per-slug history (design 1 / Track 1 Task 1.4).
    name: Merge BMF + Bencher upload (ubuntu-latest)
    runs-on: ubuntu-latest
    # Three combined gates:
    #   1. `always()` — a single matrix-leg failure (e.g. one binary
    #      timed out) must not skip the merge+upload; the operator
    #      still gets partial Bencher coverage from the surviving
    #      binaries (design's partial-coverage tolerance).
    #   2. Bot-actor guard (loop-prevention layer 3 of 3): the
    #      snapshot push step commits as `github-actions[bot]`. Skip
    #      the upload when the actor is the bot so a snapshot push
    #      cannot trigger another bench run.
    #   3. Fork-PR token guard: PRs from forks cannot read
    #      BENCHER_API_TOKEN; skip rather than fail noisily.
    if: |
      always() &&
      github.actor != 'github-actions[bot]' &&
      (github.event_name != 'pull_request' ||
       github.event.pull_request.head.repo.full_name == github.repository)
    needs: [bench]
    permissions:
      # `contents: write` covers both the read needed by
      # actions/checkout and the write needed by the snapshot-push step
      # (Task 5.5.b). The push only fires on `push` to `refs/heads/devel`;
      # PR runs and other branches keep contents:write unused.
      contents: write
      actions: read
      pull-requests: write
      checks: write
    timeout-minutes: 10

    steps:
      - name: Checkout project
        uses: actions/checkout@v4
        with:
          # Snapshot-push needs a writable working tree on `devel` so
          # `git commit` + `git push origin devel` succeeds. Detached
          # HEAD (the default for push events) cannot push back.
          ref: ${{ github.event_name == 'push' && github.ref_name || '' }}
          # Default GITHUB_TOKEN identity (`github-actions[bot]`) is the
          # token the actor-guard short-circuits on (Task 5.5.a), so
          # the push closes the loop-prevention contract.
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Download BMF artifacts
        # Pattern matches every per-binary artifact uploaded by the
        # bench matrix (`bench-bench_spsc-bmf`, `bench-bench_mpsc-bmf`,
        # `bench-bench_mpmc-bmf`, `bench-bench_unbounded-bmf`,
        # `bench-bench_latency-bmf`). Each artifact lands in its own
        # subdir under `bmf-inputs/` (no `merge-multiple`) so any future
        # filename overlap between binaries cannot silently overwrite.
        uses: actions/download-artifact@v4
        with:
          pattern: bench-*-bmf
          path: ./bmf-inputs/

      - name: List BMF inputs (debug)
        run: find bmf-inputs/ -type f -name '*.json' -print

      - name: Validate BMF inputs (drop unparseable fragments)
        # `bench-upload` runs with `if: always()`, so a matrix leg that
        # crashed mid-write can leave a truncated JSON fragment in its
        # uploaded artifact. `merge_bmf.py` exits 1 on the first malformed
        # input, which would block uploading results from the surviving
        # legs. Pre-validate each fragment with `json.load` and remove
        # any that fail to parse, emitting a `::warning::` per dropped
        # file so the operator can see which leg produced bad output.
        run: |
          while IFS= read -r -d '' f; do
            if ! python3 -c 'import json,sys; json.load(open(sys.argv[1],"r",encoding="utf-8"))' "$f" 2>/dev/null; then
              echo "::warning::Dropping unparseable BMF fragment: $f"
              rm -f "$f"
            fi
          done < <(find bmf-inputs/ -type f -name '*.json' -print0)

      - name: Verify BMF inputs present
        # If every matrix leg failed before producing JSON (or every
        # fragment was dropped as unparseable above) we have nothing to
        # merge. Fail loudly here so the workflow surfaces a clear "no
        # benchmarks ran" signal instead of crashing inside merge_bmf.py
        # with an empty argv.
        run: |
          count=$(find bmf-inputs/ -type f -name '*.json' | wc -l)
          if [ "$count" -eq 0 ]; then
            echo "::error::No valid BMF JSON fragments found in bmf-inputs/. All bench matrix legs must have failed (or produced unparseable output) before writing usable JSON." >&2
            exit 1
          fi
          echo "Found $count valid BMF JSON fragment(s) to merge."

      - name: Merge BMF JSON
        id: merge
        # `merge_bmf.py` unions per-slug measure dicts across N inputs
        # and exits 1 on (slug, measure) collisions. Pure stdlib (no
        # third-party deps), so no Python install step is needed beyond
        # the ubuntu-latest default.
        #
        # Inputs live one subdir deep under `bmf-inputs/<artifact-name>/`
        # (no `merge-multiple`); enumerate all `*.json` recursively and
        # NUL-delimit so filenames with whitespace cannot break argv
        # splitting in the future.
        run: |
          find bmf-inputs/ -type f -name '*.json' -print0 | \
            xargs -0 python3 benchmarks/merge_bmf.py merged.json

      - name: Verify deletion-safety against pre-split fixture
        # Track 2 PR 2 Task 2.7 deletion-safety guard. Asserts the
        # union of the topology-split BMFs is a strict superset of the
        # pre-split slug fixture captured from the legacy
        # bench_throughput before the split. Exit 1 with missing slugs
        # listed on stderr fails this step (and the workflow), making
        # any silent slug regression visible in the PR check summary.
        run: |
          python3 benchmarks/scripts/superset_check.py \
            tests/fixtures/pre-split-slugs.json \
            merged.json

      - name: Show BMF JSON (debug)
        run: cat merged.json

      - name: Install Bencher CLI
        uses: bencherdev/bencher@main

      - name: Bencher upload preflight
        # Always runs. Surfaces a yellow PR-check warning whenever the
        # downstream `bencher run` would be skipped, so the reason is
        # obvious from the check summary rather than the bench silently
        # appearing to "do nothing" with the data. Skip reasons:
        #   1. BENCHER_API_TOKEN secret unset (any event)
        #   2. PR event without the `bench` label (cost gate — Bencher
        #      ingest charges per metric, so PR comparisons are opt-in
        #      via label rather than firing on every cascade-rebase push)
        # Push to main/devel and workflow_dispatch never need the label.
        run: |
          if [ -z "$BENCHER_API_TOKEN" ]; then
            echo "::warning title=Bencher upload skipped::BENCHER_API_TOKEN secret is not set on this repo. The bench ran successfully and produced merged.json (visible in the 'Show BMF JSON (debug)' step), but no data is being uploaded to Bencher.dev. Set up the project at bencher.dev with slug 'lockfreequeues' and add BENCHER_API_TOKEN as a repo secret to enable upload."
            exit 0
          fi
          if [ "${{ github.event_name }}" = "pull_request" ] \
             && ! ${{ contains(github.event.pull_request.labels.*.name, 'bench') }}; then
            echo "::warning title=Bencher upload skipped::This is a pull_request event but the PR does not carry the 'bench' label. PR-time Bencher uploads are opt-in to control metric-ingest costs. Add the 'bench' label to the PR and re-run this workflow if you want a Bencher comparison report on this revision."
            exit 0
          fi
          echo "Bencher upload preconditions met; proceeding."

      # PR runs: compare against base branch and post a comment.
      # Gated on the `bench` PR label so cascade-rebases of stacked PRs
      # do not burn Bencher quota; add the label deliberately when you
      # want a comparison report.
      - name: Track PR benchmarks with Bencher
        if: |
          github.event_name == 'pull_request'
          && env.BENCHER_API_TOKEN != ''
          && contains(github.event.pull_request.labels.*.name, 'bench')
        run: |
          bencher run \
            --project lockfreequeues \
            --token '${{ secrets.BENCHER_API_TOKEN }}' \
            --branch "$GITHUB_HEAD_REF" \
            --start-point "$GITHUB_BASE_REF" \
            --start-point-hash '${{ github.event.pull_request.base.sha }}' \
            --start-point-clone-thresholds \
            --start-point-reset \
            --testbed ubuntu-latest \
            --adapter json \
            --file merged.json \
            --github-actions '${{ secrets.GITHUB_TOKEN }}' \
            --err

      # Push to main/devel: record the baseline for that branch.
      #
      # Track 6 Task 6.3: per-measure thresholds. We gate on BOTH
      #   - latency_p99_ns (upper boundary: regression = latency increase)
      #   - throughput_ops_ms (lower boundary: regression = throughput drop)
      # in a single `bencher run` invocation by repeating the
      # `--threshold-measure / --threshold-test / --threshold-max-sample-size
      # / --threshold-{upper,lower}-boundary` block per measure (Bencher CLI
      # convention; design §3 PR 6). End with `--thresholds-reset` so only
      # the explicitly-listed thresholds remain active going forward.
      #
      # NOTE on activation: per Track 6 Task 6.4, the latency threshold
      # requires ≥ 10 prior runs accumulated in Bencher to calibrate the
      # t-test baseline. Until that soak completes (post-merge), the
      # threshold is effectively dormant — Bencher will not emit alerts on
      # measures that have insufficient sample history. The configuration
      # is in place so activation is purely a function of run count, not
      # workflow edits.
      #
      # NOTE on previous measure name: the prior config used
      # `--threshold-measure throughput`; the actual measure key emitted by
      # bench_{spsc,mpsc,mpmc,unbounded}.nim is `throughput_ops_ms`, so the
      # earlier threshold never matched any measure. Track 6 corrects this.
      #
      # NOTE on continue-on-error (v4.2.0): the Bencher CLI is currently
      # rejecting the multi-measure threshold configuration with
      # "Failed to validate the model for the throughput_ops_ms Measure
      # Threshold: Invalid threshold model: Invalid model, no boundary
      # provided" even though the invocation matches the documented
      # bencher.dev pattern (see https://bencher.dev/docs/explanation/thresholds/
      # "Two-Measure Example"). The failing step short-circuits the job
      # before `Snapshot to docs assets` runs, leaving the chart on
      # docs/benchmarks.md without fresh data. As a release-day band-aid
      # we mark this step continue-on-error so the snapshot path keeps
      # flowing; the threshold gating itself remains dormant until
      # Task 6.4's 10-run soak completes anyway, so functionally nothing
      # is lost in the short term.
      #
      # TODO(post-v4.2.0): diagnose the boundary-flag binding issue.
      # Hypothesis: clap absorbs the trailing `--threshold-lower-boundary`
      # into the first measure block (latency) instead of the second
      # (throughput), so throughput's model has no boundary. Try giving
      # each measure both boundaries explicitly, splitting into two
      # `bencher run` invocations, or pinning the bencherdev/bencher
      # action to a specific tag once Bencher confirms the bug/expected
      # syntax.
      - name: Track base branch benchmarks with Bencher
        if: github.event_name == 'push' && env.BENCHER_API_TOKEN != ''
        continue-on-error: true
        run: |
          bencher run \
            --project lockfreequeues \
            --token '${{ secrets.BENCHER_API_TOKEN }}' \
            --branch "${GITHUB_REF##*/}" \
            --testbed ubuntu-latest \
            --threshold-measure latency_p99_ns \
            --threshold-test t_test \
            --threshold-max-sample-size 64 \
            --threshold-upper-boundary 0.99 \
            --threshold-measure throughput_ops_ms \
            --threshold-test t_test \
            --threshold-max-sample-size 64 \
            --threshold-lower-boundary 0.99 \
            --thresholds-reset \
            --adapter json \
            --file merged.json \
            --github-actions '${{ secrets.GITHUB_TOKEN }}' \
            --err

      # workflow_dispatch: just upload, no comparison.
      - name: Track manual benchmarks with Bencher
        if: github.event_name == 'workflow_dispatch' && env.BENCHER_API_TOKEN != ''
        run: |
          bencher run \
            --project lockfreequeues \
            --token '${{ secrets.BENCHER_API_TOKEN }}' \
            --branch "${GITHUB_REF##*/}" \
            --testbed ubuntu-latest \
            --adapter json \
            --file merged.json

      # Track 5 PR 5 Task 5.5.b: snapshot the merged BMF into the docs
      # assets tree so the chart on `docs/benchmarks.md` always points
      # at the most recent devel run. Loop-prevention against bench.yml
      # itself relies on three defensive layers:
      #   1. `paths-ignore: docs/assets/bench-results/**` on bench.yml
      #      — the snapshot push only changes files under that prefix,
      #      so bench.yml does not re-evaluate at all.
      #   2. `if: github.actor != 'github-actions[bot]'` on the parent
      #      bench / bench-upload jobs — defense-in-depth in case the
      #      paths-ignore is ever loosened.
      #   3. `[skip ci]` in the snapshot commit message (added v4.2.0,
      #      thread D1) — third defensive guard preventing recursive
      #      bench → snapshot → bench loops in edge cases where the
      #      paths-ignore evaluation order or workflow_dispatch
      #      re-runs could otherwise re-trigger. GitHub's native
      #      `[skip ci]` suppresses ALL workflows on the commit;
      #      docs.yml's chart deploy is acceptable to defer because
      #      the next non-bot push to devel will redeploy the JSON
      #      via the normal docs build path. Symmetric with the
      #      defensive fallback step's commit (which also carries
      #      `[skip ci]`).
      # Only fires on `push` to `refs/heads/devel`; tag pushes,
      # workflow_dispatch, PR runs, and main pushes do nothing here.
      - name: Snapshot to docs assets (devel push only)
        if: github.event_name == 'push' && github.ref == 'refs/heads/devel'
        run: |
          set -euo pipefail
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          mkdir -p docs/assets/bench-results
          SHA=$(git rev-parse --short HEAD)
          cp merged.json "docs/assets/bench-results/${SHA}.json"
          cp merged.json docs/assets/bench-results/latest.json
          git add docs/assets/bench-results/
          # Nothing to commit if merged.json is byte-identical to the
          # currently-checked-in latest.json (rare but possible on a
          # docs-only retrigger). `git diff --cached --quiet` exits 0
          # when there is no staged diff; in that case skip cleanly.
          if git diff --cached --quiet; then
            echo "::notice::Snapshot identical to current checked-in latest.json; skipping commit."
            exit 0
          fi
          git commit -m "chore(bench): refresh snapshot [skip ci]"
          # Long bench runs leave a wide window for `devel` to advance
          # before we push (a docs-only follow-up commit, an unrelated
          # merge, etc.); a plain `git push` would then be rejected
          # non-fast-forward and fail the entire bench-upload job.
          # Retry: fetch+rebase+push up to 3 times. bench.yml's
          # paths-ignore on docs/assets/bench-results/** prevents this
          # commit from retriggering bench.yml, so the retry loop is
          # safe regardless of how many fast-forwards happen.
          for attempt in 1 2 3; do
            if git push origin HEAD:devel; then
              exit 0
            fi
            echo "::notice::push attempt $attempt rejected; rebasing onto origin/devel and retrying."
            git fetch origin devel
            # Rebase preserves our snapshot commit on top of any new
            # commits that landed since checkout. Conflict on the
            # snapshot files themselves is impossible (no other workflow
            # writes to docs/assets/bench-results/), so a clean rebase
            # is the expected outcome.
            git rebase origin/devel
          done
          echo "::error::Snapshot push failed after 3 retries; aborting." >&2
          exit 1

      # v4.2.0 thread D1: defensive fallback snapshot.
      #
      # When `Merge BMF JSON` (id: merge) fails or is cancelled on a
      # `devel` push or `workflow_dispatch`, the regular Snapshot step
      # short-circuits the job and the chart on docs/benchmarks.md
      # would silently 404 against the missing `latest.json`. This
      # step writes a placeholder `latest.json` with `_status:
      # "fallback"` so the chart page can render an explicit "no
      # data — last attempt failed" state. Operators can pivot from
      # the embedded `_workflow_run` URL to triage.
      #
      # Loop-safety: same three layers as the regular snapshot
      # (paths-ignore + bot-actor guard + `[skip ci]` in the commit
      # message). The fallback is positioned AFTER the cost-gate-
      # guarded Bencher upload steps so a missing `bench` PR label
      # still permits this gh-pages-side snapshot path; the fallback
      # does not consume Bencher quota.
      #
      # `if:` scoping (IMP-5): only fires when `merge` outcome is
      # `failure` or `cancelled`. We deliberately do NOT fire on
      # `success` (the regular snapshot handles that) and do NOT
      # fire on `skipped` (means the job never reached merge — no
      # signal to publish).
      #
      # The placeholder JSON omits `_commit` (IMP-6); `_workflow_run`
      # is sufficient for traceability and avoids the misleading
      # impression that the placeholder corresponds to a measured
      # bench at that SHA.
      - name: Defensive snapshot fallback
        if: |
          always() && (
            (github.event_name == 'push' && github.ref == 'refs/heads/devel') ||
            (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/devel')
          ) && (steps.merge.outcome == 'failure' || steps.merge.outcome == 'cancelled')
        run: |
          set -euo pipefail
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          mkdir -p docs/assets/bench-results
          cat > docs/assets/bench-results/latest.json <<'EOF'
          {
            "_status": "fallback",
            "_reason": "merge_bmf step ${{ steps.merge.outcome }}",
            "_merge_outcome": "${{ steps.merge.outcome }}",
            "_timestamp": "${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}",
            "_workflow_run": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          }
          EOF
          git add docs/assets/bench-results/latest.json
          if git diff --cached --quiet; then
            echo "::notice::Fallback latest.json identical to current checked-in copy; skipping commit."
            exit 0
          fi
          git commit -m "bench: defensive fallback snapshot [skip ci]"
          # Same retry pattern as the regular snapshot step: fetch +
          # rebase + push up to 3 times to survive concurrent advances
          # of devel during long bench runs.
          for attempt in 1 2 3; do
            if git push origin HEAD:devel; then
              exit 0
            fi
            echo "::notice::fallback push attempt $attempt rejected; rebasing onto origin/devel and retrying."
            git fetch origin devel
            git rebase origin/devel
          done
          echo "::error::Fallback snapshot push failed after 3 retries; aborting." >&2
          exit 1