release.yml

name: CI

# ONE pipeline for everything. On EVERY push (any branch) and pull request it
# builds and tests the whole product in parallel -- the full tox matrix
# (lint/mypy/pytest), the wheel + sdist, the self-contained PyInstaller binaries
# for Linux (amd64, arm64, i686, armv7, ppc64le, s390x and riscv64 in both glibc
# and musl/Alpine flavors, plus armv6 in musl only), macOS (arm64 + amd64 on
# macOS 15, shipped; plus macOS 26/Tahoe as non-gating CI coverage) and Windows
# (amd64 + arm64), and every Docker image (8 distros, full arch set, build-only)
# -- and gates on ALL of it. The `perf` job runs in the same fan-out: it
# benchmarks this commit against the latest release tag (paired on one runner,
# see benchmarks/) and, on a release, a regression beyond a metric's limit
# fails the gate, while the resulting chart + summary are attached to the
# GitHub Release and appended to its notes.
# No SOFTWARE is published on an ordinary commit; the
# one thing that is, is documentation -- a push to `develop` publishes wiki/ to
# the GitHub wiki (the `wiki` job, ungated, since a doc is not an artifact).
#
# A release happens ONLY when either:
#   - a push to `main` carries a [release] marker at the START of the SUBJECT
#     line of any of its commits:
#         [release]          -> minor (default)
#         [release:major]    -> major
#         [release:minor]    -> minor
#         [release:patch]    -> patch
#     (if several pushed commits carry a marker, the LATEST such commit wins;
#     bodies are never scanned, so prose that merely mentions a marker cannot
#     trigger or escalate a release -- 1.3.0 shipped off a [release:patch]
#     push because a commit body discussing the bare [release] marker
#     out-bumped it), or
#   - it is started via workflow_dispatch (bump from the dropdown, or an exact
#     `tag` to release a specific X.Y.Z; the `tag` input wins over `bump`).
#
# On a release, once EVERY build + test job above has succeeded (the gate),
# and ONLY then, the pipeline publishes: the wheel + sdist to PyPI via Trusted
# Publishing (OIDC, skip-existing so a retry is a no-op), tags the commit
# (RELEASE_TOKEN so the tag can point at a commit that touches
# .github/workflows/), cuts a GitHub Release with ALL prebuilt binaries + a
# single SHA256SUMS, pushes every Docker image, and updates the Homebrew tap.
# Because the Release is gated on all binaries AND the Docker build, a broken or
# flaky arch (or Dockerfile) fails the run BEFORE anything is published -- never
# a half release. A failed publish leaves no orphan tag (tagged only after PyPI
# accepts), so a re-run cleanly retries.
#
# This file replaces the former build.yml + docker.yml + tox.yml + release.yml,
# whose binary/tox builds it deduplicates into one definition each.
#
# Example commit message (marker leads the subject line):
#     [release:minor] Add retry backoff to the HTTP reporter

on:
  push:
    branches: ["**"]  # build + test on every commit, on every branch
  pull_request:       # and on every PR (covers fork PRs, which don't push here)
  workflow_dispatch:
    inputs:
      bump:
        description: "Version bump level (ignored when 'tag' is set)"
        type: choice
        options: [patch, minor, major]
        default: patch
      tag:
        description: "Exact version to release as X.Y.Z (overrides bump); leave blank to compute the next one"
        type: string
        default: ""

# One in-flight run per (head repo, branch). A same-repo branch push and its
# PR still share a group, so the duplicate is cancelled rather than run twice.
# The group is qualified by the HEAD repository because cancel-in-progress
# evaluates on the INCOMING run: an unqualified group let a fork PR whose head
# branch was named `main` land in the push-to-main group and cancel an
# in-flight release mid-publish (its own ref is refs/pull/N/merge, so the
# expression below was true for it). main is never cancelled by main pushes
# (cancel-in-progress false there): consecutive main pushes QUEUE so releases
# serialize instead of racing, and a workflow_dispatch release is likewise
# protected from a later push cancelling it.
concurrency:
  group: ci-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.event.pull_request.head.ref || github.ref_name }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.event_name != 'workflow_dispatch' }}

# Least-privilege default for all jobs; the publish jobs opt up to the narrower
# write scopes they actually need (see each one's own permissions:).
permissions:
  contents: read

# Network hardening for transient PyPI/network blips. Runner-native jobs install
# with uv (UV_HTTP_TIMEOUT raises its per-request socket timeout; uv retries
# internally) and UV_PYTHON_DOWNLOADS=never keeps uv on the setup-python
# interpreter rather than fetching a managed one. The emulated foreign-arch
# binary jobs stay on pip inside their `docker run` containers (uv's official
# image is amd64/arm64 only and lacks musl ppc64le/s390x wheels) and read
# PIP_RETRIES/PIP_TIMEOUT, forwarded into `docker run` with `-e`. They also
# forward PIP_CACHE_DIR, pointed at an actions/cache-persisted directory in
# the mounted checkout, so the wheels pip compiles under QEMU carry over
# between runs instead of being rebuilt on every push.
env:
  PIP_RETRIES: "5"
  PIP_TIMEOUT: "60"
  UV_HTTP_TIMEOUT: "60"
  UV_PYTHON_DOWNLOADS: "never"

jobs:
  # ---------------------------------------------------------------------------
  # Decide + version (run on every event; feed both the gate and the publish).
  # ---------------------------------------------------------------------------

  # Decide whether this run is a release (and at what level), then compute the
  # version: two steps in ONE job. They ran as separate serial jobs before, but
  # each needed the same full-history checkout and every builder waited on both
  # runner spin-ups, so merging them starts the whole fan-out sooner.
  #
  # The decide step is kept strict so the trigger logic lives in a real script,
  # never a fuzzy `contains()` match. A release requires a workflow_dispatch OR
  # a push to main with a [release] marker -- a marker on any other branch, or a
  # PR, never releases (this file triggers on all branches + PRs, so the decide
  # step itself must enforce the main-only rule the old push:branches:[main]
  # filter used to).
  #
  # The version step computes the version ONCE so every builder pins the same
  # number via SETUPTOOLS_SCM_PRETEND_VERSION. It always runs (the gate builds
  # always need a version): on a release it computes the next X.Y.Z (or the
  # explicit `tag` override) and refuses if that tag already exists; otherwise
  # it emits the natural setuptools_scm dev version (e.g. 1.2.9.devN+g<sha>),
  # exactly as the old build.yml did for its per-commit builds.
  version:
    runs-on: ubuntu-latest
    outputs:
      release: ${{ steps.d.outputs.release }}
      bump: ${{ steps.d.outputs.bump }}
      new: ${{ steps.ver.outputs.new }}
      docker-matrix: ${{ steps.distros.outputs.matrix }}
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0  # full history + tags: the marker scan walks BEFORE..AFTER and setuptools_scm / tag math resolve
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Decide release
        id: d
        env:
          EVENT: ${{ github.event_name }}
          REF: ${{ github.ref }}
          INPUT_BUMP: ${{ github.event.inputs.bump }}
          BEFORE: ${{ github.event.before }}
          AFTER: ${{ github.sha }}
        run: |
          set -euo pipefail
          release=false
          bump=minor
          if [ "$EVENT" = "workflow_dispatch" ]; then
            release=true
            bump="${INPUT_BUMP:-minor}"
          elif [ "$EVENT" = "push" ] && [ "$REF" = "refs/heads/main" ]; then
            # Trigger if ANY commit introduced by this push has a [release]
            # marker -- not just the tip commit (the marker usually sits on a
            # develop commit one behind the merge commit that lands on main).
            # The range is the commits new in this push (BEFORE..AFTER); on a
            # brand-new branch BEFORE is all-zeros, so fall back to the tip.
            zero="0000000000000000000000000000000000000000"
            if [ -z "${BEFORE:-}" ] || [ "$BEFORE" = "$zero" ] \
                 || ! git rev-parse -q --verify "${BEFORE}^{commit}" >/dev/null; then
              subjects="$(git log -1 --pretty=%s "$AFTER")"
            else
              subjects="$(git log --pretty=%s "${BEFORE}..${AFTER}")"
            fi
            # Only commit SUBJECTS are scanned, and the marker must be at the
            # very start of the subject. Bodies are never scanned: prose that
            # merely mentions a marker (a changelog quote, a commit that
            # documents this very syntax, dependabot notes) must not trigger
            # or escalate a release -- that is exactly how 1.3.0 shipped from
            # a [release:patch] push. If several commits carry a marker, the
            # LATEST one wins (git log lists newest first); a bare [release]
            # counts as minor.
            marker="$(printf '%s\n' "$subjects" \
              | grep -oiE '^\[release(:(major|minor|patch))?\]' \
              | head -n1 \
              | tr '[:upper:]' '[:lower:]' || true)"
            if [ -n "$marker" ]; then
              release=true
              case "$marker" in
                "[release:major]") bump=major ;;
                "[release:patch]") bump=patch ;;
                *)                 bump=minor ;;
              esac
            fi
          fi
          # else: a PR or a non-main push -> build + test only, never release.
          echo "release=$release" >> "$GITHUB_OUTPUT"
          echo "bump=$bump" >> "$GITHUB_OUTPUT"
          echo "::notice::release=$release bump=$bump (event=$EVENT ref=$REF)"
      - name: Compute version
        id: ver
        env:
          RELEASE: ${{ steps.d.outputs.release }}
          BUMP: ${{ steps.d.outputs.bump }}
          OVERRIDE: ${{ github.event.inputs.tag }}
        run: |
          set -euo pipefail
          if [ "$RELEASE" != "true" ]; then
            # Build-only run: resolve setuptools_scm's natural dev version off
            # git in a throwaway env (no venv/install left behind).
            new="$(uv run --no-project --with setuptools-scm python -m setuptools_scm)"
            echo "new=$new" >> "$GITHUB_OUTPUT"
            echo "::notice::Build-only at version $new (no release)."
            exit 0
          fi

          git fetch --tags --force
          if [ -n "${OVERRIDE:-}" ]; then
            # Explicit override from workflow_dispatch: release exactly this
            # version instead of the computed next one. Tags in this repo are
            # bare X.Y.Z and the rest of the pipeline (HISTORY.md lookup, asset
            # names, the PyPI/scm version) assumes that shape, so reject anything
            # else rather than silently building a malformed release.
            new="$OVERRIDE"
            if ! printf '%s' "$new" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
              echo "::error::Invalid tag '$new'; expected X.Y.Z (digits only, no leading 'v')." >&2
              exit 1
            fi
            echo "::notice::Releasing $new (explicit tag override)"
          else
            latest=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n1)
            latest=${latest:-0.0.0}
            IFS='.' read -r major minor patch <<<"$latest"
            case "$BUMP" in
              major) major=$((major + 1)); minor=0; patch=0 ;;
              minor) minor=$((minor + 1)); patch=0 ;;
              patch) patch=$((patch + 1)) ;;
            esac
            new="${major}.${minor}.${patch}"
            echo "::notice::Releasing $new (previous $latest, bump=$BUMP)"
          fi

          # Never clobber an existing tag (a failed publish leaves no orphan tag,
          # so a clean retry is still possible).
          if git rev-parse -q --verify "refs/tags/$new" >/dev/null; then
            echo "::error::Tag $new already exists; refusing to re-release." >&2
            exit 1
          fi
          echo "new=$new" >> "$GITHUB_OUTPUT"
      # The ONE distro matrix (.github/docker-matrix.json): `docker` (the
      # build-only gate) and `docker-push` both fromJSON this output, so the
      # two lists can never drift apart (they were written twice and did).
      # The gate ignores the per-row `suffix`; only the push tags use it.
      - name: Emit the docker distro matrix
        id: distros
        run: |
          set -euo pipefail
          {
            echo 'matrix<<JSON'
            cat .github/docker-matrix.json
            echo 'JSON'
          } >> "$GITHUB_OUTPUT"

  # ---------------------------------------------------------------------------
  # Gate: tests + all binaries + all Docker images. Runs on EVERY event, in
  # parallel. The publish jobs below need every one of these to succeed.
  # ---------------------------------------------------------------------------

  # lint + mypy + bandit in one job: each env finishes in well under a minute,
  # so a second runner spin-up costs more wall clock than running them serially.
  tox-static:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7.0.1
      # This repository is LF-only (see .gitattributes). Fail fast if any
      # tracked blob ever reaches the index with CRLF or mixed line endings,
      # e.g. one that slipped past `text=auto` normalization by being marked
      # binary or committed by a client that ignored .gitattributes.
      - name: Guard against CRLF line endings
        run: |
          crlf="$(git ls-files --eol | grep -E 'i/(crlf|mixed)' || true)"
          if [ -n "$crlf" ]; then
            echo "::error::Tracked files with CRLF/mixed line endings (this repo is LF-only):"
            echo "$crlf"
            exit 1
          fi
      - uses: actions/setup-python@v7.0.0
      # tox-uv pulls in uv and makes tox provision envs + install deps with it.
      - run: pip install tox tox-uv
      - run: tox -e lint,mypy,bandit,openapi

  # Dependency-license gate. cronstable's core is MIT and it BUNDLES its deps
  # (the PyInstaller binaries and Docker images vendor the whole tree), so a
  # copyleft (GPL/AGPL) or non-open source-available (SSPL/BUSL) dependency must
  # never slip in. scripts/check_licenses.py reads the INSTALLED dist metadata
  # (no third-party scanner) and fails on a disallowed license; weak file-scoped
  # copyleft (LGPL/MPL) is reported but allowed. It installs the runtime plus
  # every distributable extra (`speedups`, `push`, and `discovery` all ride in
  # the binaries and Docker images) so nothing the artifacts can carry escapes
  # the scan. zeroconf (discovery) is LGPL-2.1: expected in the report, and
  # shipped with its compliance kit (in-binary notice, Release source archive,
  # public build recipe). See LICENSING.md.
  licenses:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Install runtime + distributable extras
        run: |
          set -euo pipefail
          uv venv --python 3.14
          uv pip install ".[speedups,push,discovery]"
      - name: Check dependency licenses
        run: uv run python .github/scripts/check_licenses.py

  tox:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]  # macOS is POSIX like Linux; add macos-latest to cover it too
        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
        experimental: [false]
        include:
          # Windows on ARM64: a gating row on the latest stable Python so the
          # runtime is exercised on win-arm64 (the released .exe targets it too).
          - os: windows-11-arm
            python: '3.14'
            experimental: false
          # Python 3.15 is in beta. Run it for early signal, but never let it
          # gate CI -> continue-on-error. allow-prereleases lets setup-python
          # pick up the beta (a no-op for the stable rows).
          - os: ubuntu-latest
            python: '3.15'
            experimental: true
    runs-on: ${{ matrix.os }}
    continue-on-error: ${{ matrix.experimental }}
    # The suite runs in 2-9 min per cell (Windows is the slow end); 30 still
    # bounds a hung asyncio test while leaving headroom for a degraded
    # runner VM, which has cost us whole runs at 20.
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: ${{ matrix.python }}
          allow-prereleases: true
      - run: pip install tox tox-uv
      # requirements_dev.txt installs the playwright LIBRARY into the tox env,
      # but pip cannot fetch a browser, and without one the client/daemon cron
      # engine differential (tests/test_web_engine_parity.py) self-skips, which
      # is why it used to run nowhere at all: the dashboard ships a SECOND
      # implementation of the schedule dialect, and nothing compared it against
      # the daemon's outside a dev machine where someone had run
      # `playwright install`.
      #
      # Only this cell: the download is ~150 MB and the differential is
      # platform-independent (it replays the same golden corpus through the
      # same two engines), so a second OS or Python row buys no signal and
      # costs a browser fetch per row. The other cells keep self-skipping.
      # Installed from the requirements_dev.txt line verbatim, so this step and
      # the tox env normally resolve the same release and the browser
      # downloaded here is the build that env goes looking for in the shared
      # ms-playwright cache. The line carries no version pin, and the two
      # installs resolve independently (pip here, uv inside tox), so on a skew
      # the env's playwright wants a browser revision this step did not fetch,
      # chromium.launch() raises, and the differential self-skips: silently
      # green, with nothing comparing the second engine again. The enforcement
      # step below turns that silence into a red cell.
      - name: Install Chromium for the web engine differential
        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.14'
        run: |
          set -euo pipefail
          pip install "$(grep -E '^playwright' requirements_dev.txt)"
          python -m playwright install --with-deps chromium
      - run: tox -e py
      # The differential self-skips wherever Chromium is missing (every other
      # cell, by design), so THIS cell must prove it actually ran: re-drive it
      # through the tox env's own interpreter (and therefore the env's own
      # resolved playwright, the one that must find the browser fetched above)
      # and require a pass, not a skip. Cheap (<1s after the suite), and
      # without it a pip/uv resolution skew quietly restores the
      # "nothing compares the second engine" state this cell exists to end.
      # The check reads pytest's junitxml counts (at least one test, zero
      # failures, zero errors, zero skips) rather than grepping stdout for a
      # literal "1 passed", which a second test in the file would flip to a
      # false red.
      - name: Enforce the web engine differential ran (no silent skip)
        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.14'
        run: |
          set -euo pipefail
          .tox/py/bin/python -m pytest \
            tests/test_web_engine_parity.py \
            tests/test_web_heat_e2e.py \
            tests/test_web_drawer_e2e.py \
            -v -rs --junitxml=parity-enforce.xml
          .tox/py/bin/python - <<'EOF'
          import xml.etree.ElementTree as ET
          totals = {"tests": 0, "failures": 0, "errors": 0, "skipped": 0}
          for suite in ET.parse("parity-enforce.xml").getroot().iter("testsuite"):
              for key in totals:
                  totals[key] += int(suite.get(key, 0))
          print("parity differential:", totals)
          assert totals["tests"] >= 1, "no parity test was collected"
          assert totals["failures"] == 0 and totals["errors"] == 0
          assert totals["skipped"] == 0, (
              "a parity test skipped in the one cell that provisions "
              "Chromium: the browser install or resolution went stale"
          )
          EOF
      # Every matrix cell uploads its own coverage.xml; Codecov merges them by
      # flag into one combined number. fail_ci_if_error stays false so a Codecov
      # outage never reds the build (and fork PRs with no token still pass).
      - name: Upload coverage to Codecov
        if: ${{ !cancelled() }}
        uses: codecov/codecov-action@v7.0.0
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage.xml
          flags: ${{ matrix.os }}-py${{ matrix.python }}
          fail_ci_if_error: false

  # Wheel + sdist, built and `twine check`ed exactly as it will be published to
  # PyPI. Uploaded as an artifact the `release` job publishes verbatim (so the
  # exact bytes that were checked here are what ship).
  dist:
    needs: version
    runs-on: ubuntu-latest
    steps:
      # Shallow on purpose: SETUPTOOLS_SCM_PRETEND_VERSION pins the version, so
      # setuptools_scm never walks history here, and its git file-finder (which
      # the wheel/sdist build does use) only needs the checked-out tree.
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Build distributions
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          uv build                                      # wheel + sdist into dist/
          uvx twine check dist/*.whl dist/*.tar.gz       # twine, run ephemerally
      # `twine check` validates metadata and renders the long description; it
      # does NOT look at file size, and neither does the publish action. A 1.2.31
      # sdist that had grown past PyPI's per-file cap therefore sailed through
      # every gate and was rejected two hours later, at upload, after the wheel
      # had already been accepted. Catch it here instead, in seconds.
      - name: Check artifacts against PyPI's per-file size limit
        run: |
          set -euo pipefail
          # warehouse: MAX_FILESIZE = 100 * ONE_MIB (constants.py). The error
          # text says "100 MB" but the value is 100 MiB.
          limit=104857600
          # Fail well below the cap: a release that squeaks under today is one
          # screenshot away from failing, and the sdist ships every git-tracked
          # file (see MANIFEST.in), so it grows with the repo, not the code.
          warn=94371840
          status=0
          for f in dist/*.whl dist/*.tar.gz; do
            size=$(wc -c < "$f")
            printf '%10d bytes  %s\n' "$size" "$f"
            if [ "$size" -ge "$warn" ]; then
              pct=$(( size * 100 / limit ))
              echo "::error file=MANIFEST.in::$(basename "$f") is ${size} bytes, ${pct}% of PyPI's ${limit}-byte per-file limit. Prune it (MANIFEST.in) before releasing."
              status=1
            fi
          done
          exit "$status"
      - uses: actions/upload-artifact@v7.0.1
        with:
          name: dist
          path: |
            dist/*.whl
            dist/*.tar.gz
          if-no-files-found: error
          retention-days: 7

  # Self-contained glibc PyInstaller binaries (amd64, arm64) on native runners
  # (no QEMU). The per-arch `--version` smoke test catches a bad bundle here.
  # These target glibc (the Ubuntu runner's libc); `binaries-container` covers
  # Alpine/musl hosts and the remaining glibc arches.
  binaries:
    needs: version
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            runner: ubuntu-24.04
          - arch: arm64
            runner: ubuntu-24.04-arm
    runs-on: ${{ matrix.runner }}
    steps:
      # Shallow on purpose: SETUPTOOLS_SCM_PRETEND_VERSION pins the version, so
      # setuptools_scm never walks history here, and its git file-finder (which
      # the wheel/sdist build does use) only needs the checked-out tree.
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Build binary
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          # Runner-native, all-wheels arch: install into a throwaway uv venv and
          # freeze from it with `uv run` (uv discovers the setup-python 3.14).
          uv venv --python 3.14
          uv pip install pyinstaller==6.21.0  # pin matches pyinstaller/Dockerfile
          uv pip install .                     # bakes the pinned version into cronstable/version.py
          # Bundle uvloop (the `speedups` extra) so the binary runs the faster
          # event loop. Install a wheel where one exists, else build it from
          # sdist (ship uvloop as broadly as it compiles); a failed install
          # falls back to asyncio. The shared script then has verify_extra.py
          # prove the result actually runs a loop (a source build can
          # miscompile under emulation) and uninstalls it if not, so a broken
          # uvloop is never frozen in and the binary cleanly uses asyncio.
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh uvloop "uvloop>=0.19" soft "using asyncio"
          # Bundle orjson (the `speedups` extra) to accelerate the durable-state
          # and cluster JSON paths; amd64/arm64 and macOS ship wheels (no Rust
          # needed). The shared script round-trip-verifies it and drops a broken
          # build, so the binary falls back to stdlib json (cronstable/_json).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_orjson.sh
          # Bundle pynacl (the `push` extra): abi3 wheels cover amd64/arm64,
          # so on this lane absence means a broken build, never a missing
          # wheel. Install and verify are HARD failures here: a soft-fail
          # would let a transient index blip silently ship the advertised
          # push channel disabled. verify_extra.py round-trips a real
          # sealed box so a miscompiled libsodium also fails the job.
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh pynacl "pynacl>=1.5" hard
          # Bundle zeroconf (the `discovery` extra) for web.bonjour. Pure
          # Python with optional speedups, so the install works on every
          # arch and is a HARD failure too. It is LGPL-2.1: the notice
          # ships inside the binary (--third-party-licenses), the source
          # archive is attached to the Release, and the public build
          # recipe is the relink path. See LICENSING.md.
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh zeroconf "zeroconf>=0.132" hard
          uv run pyinstaller pyinstaller/cronstable.spec
          dist/cronstable --version            # smoke test: fails the job if the bundle is broken
          # Prove the FROZEN bundle reaches PyNaCl and zeroconf too: a
          # push-plus-bonjour config passes --validate-config only when
          # both import inside the binary (both fail closed otherwise),
          # catching an analysis or hiddenimport miss that --version
          # cannot.
          dist/cronstable --validate-config -c pyinstaller/smoke-push.yaml
          mv dist/cronstable "dist/cronstable-linux-${{ matrix.arch }}"
      - uses: actions/upload-artifact@v7.0.1
        with:
          name: cronstable-linux-${{ matrix.arch }}
          path: dist/cronstable-linux-${{ matrix.arch }}
          if-no-files-found: error
          retention-days: 7

  # Self-contained container-built Linux binaries, one per arch x libc pair.
  # PyInstaller is not a cross-compiler and the runners are glibc, so every
  # row builds inside `docker run --platform` (checkout + upload stay on the
  # host). musl rows build on python:3.14-alpine and ship with a `-musl`
  # suffix for Alpine/musl hosts; glibc rows build on python:3.14-slim and
  # cover the arches the native `binaries` job has no runner for. amd64,
  # arm64 and i686 execute natively; armv7, armv6, ppc64le, s390x and
  # riscv64 run under QEMU. armv6 is musl-only (Debian/glibc ships no
  # arm32v6); glibc amd64/arm64 are the native job above. Same pyinstaller
  # pin and `--version` smoke test as that job; the per-libc bits (base
  # image, package-manager commands, artifact suffix) ride the matrix.
  binaries-container:
    needs: version
    strategy:
      fail-fast: false
      matrix:
        libc: [musl, glibc]
        arch: [amd64, arm64, i686, armv7, armv6, ppc64le, s390x, riscv64]
        exclude:
          # glibc amd64/arm64 build natively in `binaries`; armv6 is musl-only
          - { libc: glibc, arch: amd64 }
          - { libc: glibc, arch: arm64 }
          - { libc: glibc, arch: armv6 }
        include:
          # per-libc: base image, artifact suffix, and the package-manager
          # commands the build script splices in (no quote characters in any
          # of them; they are injected into a single-quoted sh -c script)
          - libc: musl
            image: python:3.14-alpine
            suffix: -musl
            toolchain: 'retry 5 apk add --no-cache build-base libffi-dev zlib-dev'
            nacl_tools: 'retry 3 apk add --no-cache libffi-dev make >/dev/null 2>&1 || true'
            rust_setup: '. /src/.github/scripts/retry.sh && retry 5 apk add --no-cache curl && retry 3 curl --proto =https --tlsv1.2 --retry 5 --retry-connrefused --retry-delay 5 -sSfo /tmp/rustup.sh https://sh.rustup.rs && env CARGO_HOME=/opt/cargo RUSTUP_HOME=/opt/rustup sh /tmp/rustup.sh -y --default-toolchain stable --profile minimal --no-modify-path'
          - libc: glibc
            image: python:3.14-slim
            suffix: ''
            toolchain: 'retry 5 apt-get -o Acquire::Retries=5 update && retry 5 apt-get -o Acquire::Retries=5 install -y --no-install-recommends build-essential libffi-dev zlib1g-dev'
            nacl_tools: 'retry 3 apt-get -o Acquire::Retries=5 install -y --no-install-recommends libffi-dev make >/dev/null 2>&1 || true'
            rust_setup: '. /src/.github/scripts/retry.sh && retry 5 apt-get -o Acquire::Retries=5 update && retry 5 apt-get -o Acquire::Retries=5 install -y --no-install-recommends curl ca-certificates && retry 3 curl --proto =https --tlsv1.2 --retry 5 --retry-connrefused --retry-delay 5 -sSfo /tmp/rustup.sh https://sh.rustup.rs && env CARGO_HOME=/opt/cargo RUSTUP_HOME=/opt/rustup sh /tmp/rustup.sh -y --default-toolchain stable --profile minimal --no-modify-path'
          # per-arch: docker platform, runner, and whether QEMU is needed
          # (amd64/arm64/i686 execute natively on the runners)
          - { arch: amd64, platform: linux/amd64, runner: ubuntu-24.04 }
          - { arch: arm64, platform: linux/arm64, runner: ubuntu-24.04-arm }
          - { arch: i686, platform: linux/386, runner: ubuntu-24.04 }
          - { arch: armv7, platform: linux/arm/v7, runner: ubuntu-24.04, qemu: true }
          - { arch: armv6, platform: linux/arm/v6, runner: ubuntu-24.04, qemu: true }
          - { arch: ppc64le, platform: linux/ppc64le, runner: ubuntu-24.04, qemu: true }
          - { arch: s390x, platform: linux/s390x, runner: ubuntu-24.04, qemu: true }
          - { arch: riscv64, platform: linux/riscv64, runner: ubuntu-24.04, qemu: true }
    runs-on: ${{ matrix.runner }}
    steps:
      # Shallow on purpose: SETUPTOOLS_SCM_PRETEND_VERSION pins the version, so
      # setuptools_scm never walks history here, and its git file-finder (which
      # the wheel/sdist build does use) only needs the checked-out tree.
      - uses: actions/checkout@v7.0.1
      # Persist pip's cache (otherwise lost with the runner) in the workspace,
      # where the build container sees it at /src/.pip-cache via the bind
      # mount and the PIP_CACHE_DIR forwarded below. pip keeps the wheels it
      # BUILDS from sdists in this cache, so the slow QEMU compiles (uvloop,
      # orjson's Rust build, pynacl's bundled libsodium, the musl aiohttp
      # stack, PyInstaller's own bootloader) happen once per dependency bump
      # instead of on every push; install_orjson.sh's plain-pip first attempt
      # then finds the cached wheel and skips the rustup toolchain entirely.
      # Resolution still queries the index every run, so which VERSIONS
      # install is unchanged, and the verify probes still run against the
      # installed result; the cache only skips re-downloading and re-compiling
      # artifacts pip validates by hash. Keyed per arch AND libc: a wheel
      # source-built on glibc and one built on musl both carry the plain
      # linux_<arch> tag, so a shared cache could hand one row the other's
      # ABI-incompatible build. The key's hashFiles covers pyproject.toml and
      # this workflow, where the dep floors and the pyinstaller pin live;
      # restore-keys seeds the rebuild from the previous cache when either
      # file changes.
      - name: Restore pip cache (QEMU-built wheels)
        id: pip-cache
        uses: actions/cache/restore@v6.1.0
        with:
          path: .pip-cache
          key: pip-${{ matrix.libc }}-${{ matrix.arch }}-${{ hashFiles('pyproject.toml', '.github/workflows/release.yml') }}
          restore-keys: |
            pip-${{ matrix.libc }}-${{ matrix.arch }}-
      # Register binfmt/QEMU so `docker run --platform` can execute a foreign-arch
      # container. amd64/arm64/i686 run natively and skip this.
      - if: ${{ matrix.qemu }}
        uses: docker/setup-qemu-action@v4.2.0
      # Pull the base image in its own retried step. Docker Hub times out often
      # enough to red a release on its own (a 15s connect timeout to
      # registry-1.docker.io took the s390x row down mid-release), and pulling
      # here keeps the retry off the build below: that one runs for up to an
      # hour under QEMU and must never be repeated for a registry blip.
      # pull_base adds registry failover on top of the retries: the
      # 2026-07-25 Hub outage outlived five attempts, so a same-digest
      # mirror (ECR Public, then mirror.gcr.io) now backstops the pull.
      - name: Pull the build image
        run: |
          set -euo pipefail
          . .github/scripts/retry.sh
          pull_base ${{ matrix.image }} ${{ matrix.platform }}
      - name: Build binary (${{ matrix.libc }} container)
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          docker run --rm --platform ${{ matrix.platform }} \
            -e SETUPTOOLS_SCM_PRETEND_VERSION \
            -e PIP_RETRIES -e PIP_TIMEOUT \
            -e PIP_CACHE_DIR=/src/.pip-cache \
            -v "$PWD:/src" -w /src \
            ${{ matrix.image }} sh -euc '
              # The checkout is mounted at /src, so the runner-side retry helper
              # is reachable in here too. Neither apk nor apt retries hard
              # enough on its own, and a failed index fetch is a hard job
              # failure, so the matrix-provided commands wrap themselves in it.
              . /src/.github/scripts/retry.sh
              # pip refuses to use a cache directory it does not own: this
              # container runs as root while the bind-mounted workspace is
              # the runner user, so without the chown every pip call logs
              # "The cache has been disabled" and the whole persisted cache
              # stores nothing. The host-side step after the build hands
              # ownership back so the cache save can read it.
              mkdir -p /src/.pip-cache && chown -R root:root /src/.pip-cache
              # Per-libc C toolchain + strip (the spec sets strip=True), plus
              # libffi/zlib headers for the deps that ship no wheel for this
              # libc/arch and fall back to compiling from sdist (notably the
              # i686 aiohttp stack; propcache on armv7). The full-wheel arches
              # leave the toolchain unused.
              ${{ matrix.toolchain }}
              pip install --upgrade pip
              pip install pyinstaller==6.21.0   # pin matches the other binary jobs
              pip install .                     # bakes the pinned version into cronstable/version.py
              # Bundle uvloop (the `speedups` extra): a wheel where one exists
              # (amd64/arm64), else a source build. The shared script has
              # verify_extra.py prove the result runs a loop (a source build
              # can miscompile under QEMU) and uninstalls it otherwise, so a
              # broken uvloop is never frozen in; the binary then cleanly
              # falls back to asyncio.
              sh pyinstaller/install_extra.sh uvloop "uvloop>=0.19" soft "using asyncio"
              # Bundle orjson (the `speedups` extra): a wheel on amd64/arm64,
              # else a Rust source build. RUST_SETUP (per-libc, from the
              # matrix) installs a CURRENT Rust via rustup (distro rustc is
              # older than the orjson MSRV) only when the wheel is missing;
              # the shared script round-trip-verifies the result and drops a
              # broken QEMU build -> stdlib json fallback. install_orjson.sh
              # runs RUST_SETUP via `sh -c`, a fresh shell, so the command
              # sources the retry helper itself; rustup is fetched to a file
              # and then executed rather than piped straight into sh: curl
              # retries cannot un-feed a truncated script to an interpreter
              # that has already started running it.
              RUST_SETUP="${{ matrix.rust_setup }}" sh pyinstaller/install_orjson.sh
              # Bundle pynacl (the `push` extra): wheels on amd64/arm64, else
              # a plain-C source build (bundled libsodium, no Rust; the
              # libffi/make toolchain is best-effort). Soft on this lane
              # only: a build that fails the sealed-box round-trip is
              # uninstalled, so the binary never ships a miscompiled
              # libsodium (push fails closed).
              ${{ matrix.nacl_tools }}
              sh pyinstaller/install_extra.sh pynacl "pynacl>=1.5" soft "push extra not bundled"
              # Bundle zeroconf (the `discovery` extra): pure Python with
              # optional speedups, so a HARD install even under QEMU. It
              # is LGPL-2.1; the in-binary notice, Release source
              # archive, and public build recipe are the compliance kit
              # (see LICENSING.md).
              sh pyinstaller/install_extra.sh zeroconf "zeroconf>=0.132" hard
              pyinstaller pyinstaller/cronstable.spec
              dist/cronstable --version            # smoke test, native or emulated on its own libc
              # Whenever the build env kept pynacl, the frozen binary
              # must reach it (and zeroconf) too: the push-plus-bonjour
              # config validates only when both import inside the bundle.
              if python -c "import nacl" 2>/dev/null; then
                dist/cronstable --validate-config -c pyinstaller/smoke-push.yaml
              fi
              mv dist/cronstable dist/cronstable-linux-${{ matrix.arch }}${{ matrix.suffix }}
            '
      # The container runs as root and pip creates its cache files via
      # tempfile (mode 0600), so without this the runner-user tar in
      # actions/cache's save step cannot read them: the save fails with a
      # permissions warning the job ignores, and every push recompiles the
      # QEMU wheels the cache exists to keep.
      - name: Make the pip cache readable by the cache save
        run: |
          set -euo pipefail
          if [ -d .pip-cache ]; then
            sudo chown -R "$(id -u):$(id -g)" .pip-cache
          fi
      # Branch-gated like the docker job's buildx export, and for the same
      # reason: the Actions cache is ONE 10 GB pool per repository, shared
      # with that exporter's multi-GB layer blobs, and this job alone is 13
      # matrix rows. Writing from every branch and every fork PR would evict
      # the layer cache the docker build depends on. Every other branch
      # still RESTORES through to what develop and main stored, which is
      # where the QEMU compile savings actually come from.
      - name: Save pip cache (long-lived branches only)
        if: ${{ steps.pip-cache.outputs.cache-hit != 'true' && (github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main') }}
        uses: actions/cache/save@v6.1.0
        with:
          path: .pip-cache
          key: pip-${{ matrix.libc }}-${{ matrix.arch }}-${{ hashFiles('pyproject.toml', '.github/workflows/release.yml') }}
      - uses: actions/upload-artifact@v7.0.1
        with:
          name: cronstable-linux-${{ matrix.arch }}${{ matrix.suffix }}
          path: dist/cronstable-linux-${{ matrix.arch }}${{ matrix.suffix }}
          if-no-files-found: error
          retention-days: 7

  # Self-contained macOS binaries. The shipped pair is macOS 15 (arm64 + amd64),
  # signed + notarized on a release. macOS 26 (Tahoe) is built too for early
  # OS-version breakage signal, but it is CI-ONLY: continue-on-error so a flaky
  # Tahoe build never blocks a release, and it is neither signed nor attached.
  # `ship` picks the shipped rows; `asset` names the artifact (the shipped ones
  # keep the bare `macos-<arch>` names the Release + Homebrew formula expect).
  binaries-macos:
    needs: version
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: arm64
            runner: macos-15          # macOS 15, Apple Silicon -- shipped
            ship: true
            asset: macos-arm64
          - arch: amd64
            runner: macos-15-intel    # macOS 15, Intel -- shipped
            ship: true
            asset: macos-amd64
          - arch: arm64
            runner: macos-26          # macOS 26 (Tahoe), Apple Silicon -- CI only
            ship: false
            asset: macos26-arm64
          - arch: amd64
            runner: macos-26-intel    # macOS 26 (Tahoe), Intel -- CI only
            ship: false
            asset: macos26-amd64
    runs-on: ${{ matrix.runner }}
    # The macOS 26 rows are coverage-only: never let them gate a release.
    continue-on-error: ${{ !matrix.ship }}
    steps:
      # Shallow on purpose: SETUPTOOLS_SCM_PRETEND_VERSION pins the version, so
      # setuptools_scm never walks history here, and its git file-finder (which
      # the wheel/sdist build does use) only needs the checked-out tree.
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'  # set explicitly; don't rely on the runner's preinstalled patch level
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Build binary
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          # Runner-native, all-wheels arch: install into a throwaway uv venv and
          # freeze from it with `uv run` (uv discovers the setup-python 3.14).
          uv venv --python 3.14
          uv pip install pyinstaller==6.21.0  # pin matches the Linux jobs
          uv pip install .                     # bakes the pinned version into cronstable/version.py
          # Bundle uvloop (the `speedups` extra) for the faster event loop; macOS
          # ships wheels for both arches. The shared script has verify_extra.py
          # confirm it imports and runs a loop, else uninstalls it so the binary
          # falls back to asyncio.
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh uvloop "uvloop>=0.19" soft "using asyncio"
          # Bundle orjson (the `speedups` extra); macOS ships wheels (no Rust).
          # The shared script round-trip-verifies it and drops a broken build, so
          # the binary falls back to stdlib json (cronstable/_json).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_orjson.sh
          # Bundle pynacl (the `push` extra); macOS ships universal2
          # wheels, so absence means a broken build. Install and verify
          # are HARD failures on this lane (a soft-fail would silently
          # ship the advertised push channel disabled).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh pynacl "pynacl>=1.5" hard
          # Bundle zeroconf (the `discovery` extra): pure Python, wheels
          # on both arches, HARD failure. LGPL-2.1; in-binary notice +
          # Release source archive + public build recipe (LICENSING.md).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh zeroconf "zeroconf>=0.132" hard
          uv run pyinstaller pyinstaller/cronstable.spec
          dist/cronstable --version            # smoke test: fails the job if the bundle is broken
          # Prove the FROZEN bundle reaches PyNaCl and zeroconf too (both
          # fail closed at config validation when they cannot import).
          dist/cronstable --validate-config -c pyinstaller/smoke-push.yaml
          # Assert the binary is the intended native arch: Rosetta would happily
          # run an x86_64 build on the arm64 runner and let the smoke test pass,
          # silently producing a mislabelled asset. `file` reports x86_64/arm64.
          case "${{ matrix.arch }}" in
            amd64) want=x86_64 ;;
            arm64) want=arm64 ;;
          esac
          file dist/cronstable | grep -q "$want"
      # Developer ID sign + notarize the SHIPPED binary in place, on a release
      # only. Guarded on the cert secret too: if the signing secrets are not
      # configured, the step warns and exits 0, shipping an unsigned binary.
      # Renaming after signing is safe -- the notarization ticket is keyed to the
      # code signature (cdhash), not the filename -- so this runs before the `mv`.
      - name: Sign and notarize
        if: ${{ needs.version.outputs.release == 'true' && matrix.ship }}
        env:
          MACOS_CERT_P12_BASE64: ${{ secrets.MACOS_CERT_P12_BASE64 }}
          MACOS_CERT_PASSWORD: ${{ secrets.MACOS_CERT_PASSWORD }}
          MACOS_SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}
          MACOS_NOTARY_KEY_BASE64: ${{ secrets.MACOS_NOTARY_KEY_BASE64 }}
          MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
          MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
        run: |
          set -euo pipefail
          if [ -z "${MACOS_CERT_P12_BASE64:-}" ]; then
            echo "::warning::macOS signing secrets not set; shipping an unsigned, unnotarized binary."
            exit 0
          fi

          # Import the Developer ID cert into a throwaway, randomly-keyed
          # keychain scoped to this runner (never the login keychain).
          KEYCHAIN="$RUNNER_TEMP/build.keychain-db"
          KEYCHAIN_PW="$(uuidgen)"
          security create-keychain -p "$KEYCHAIN_PW" "$KEYCHAIN"
          security set-keychain-settings -lut 21600 "$KEYCHAIN"
          security unlock-keychain -p "$KEYCHAIN_PW" "$KEYCHAIN"
          echo "$MACOS_CERT_P12_BASE64" | base64 --decode > "$RUNNER_TEMP/cert.p12"
          security import "$RUNNER_TEMP/cert.p12" -P "$MACOS_CERT_PASSWORD" \
            -t cert -f pkcs12 -k "$KEYCHAIN" -T /usr/bin/codesign
          # Let codesign use the key non-interactively.
          security set-key-partition-list -S apple-tool:,apple:,codesign: \
            -s -k "$KEYCHAIN_PW" "$KEYCHAIN" >/dev/null
          security list-keychains -d user -s "$KEYCHAIN" login.keychain-db

          # Sign with the hardened runtime + secure timestamp (both required for
          # notarization) and the PyInstaller entitlements, then verify.
          codesign --force --options runtime --timestamp \
            --entitlements pyinstaller/entitlements.plist \
            --keychain "$KEYCHAIN" \
            --sign "$MACOS_SIGN_IDENTITY" dist/cronstable
          codesign --verify --strict --verbose=2 dist/cronstable

          # Notarize: the zip is just the upload transport; the ticket binds to
          # the binary's signature, so we keep shipping the bare signed binary.
          echo "$MACOS_NOTARY_KEY_BASE64" | base64 --decode > "$RUNNER_TEMP/AuthKey.p8"
          ditto -c -k dist/cronstable "$RUNNER_TEMP/cronstable.zip"
          xcrun notarytool submit "$RUNNER_TEMP/cronstable.zip" \
            --key "$RUNNER_TEMP/AuthKey.p8" \
            --key-id "$MACOS_NOTARY_KEY_ID" \
            --issuer "$MACOS_NOTARY_ISSUER_ID" \
            --wait
      - name: Rename binary
        run: mv dist/cronstable "dist/cronstable-${{ matrix.asset }}"
      - uses: actions/upload-artifact@v7.0.1
        with:
          name: cronstable-${{ matrix.asset }}
          path: dist/cronstable-${{ matrix.asset }}
          if-no-files-found: error
          retention-days: 7

  # Self-contained Windows binaries: amd64 on the hosted runner, arm64 on the
  # windows-11-arm runner. Any C-extension dep lacking a win_arm64 wheel (parts
  # of the aiohttp stack, ruamel.yaml.clib) compiles from sdist via the runner's
  # Visual Studio ARM64 toolchain. Same pyinstaller pin + `--version` smoke test;
  # the assets are cronstable-windows-<arch>.exe. Steps use bash (git bash ships
  # on the Windows runners).
  binaries-windows:
    needs: version
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            runner: windows-latest
          - arch: arm64
            runner: windows-11-arm
    runs-on: ${{ matrix.runner }}
    defaults:
      run:
        shell: bash
    steps:
      # Shallow on purpose: SETUPTOOLS_SCM_PRETEND_VERSION pins the version, so
      # setuptools_scm never walks history here, and its git file-finder (which
      # the wheel/sdist build does use) only needs the checked-out tree.
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Build binary
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          # Runner-native (uv ships a win_arm64 build too); install into a
          # throwaway uv venv and freeze from it with `uv run`.
          uv venv --python 3.14
          uv pip install pyinstaller==6.21.0  # pin matches the Linux/macOS jobs
          uv pip install .                     # bakes the pinned version into cronstable/version.py
          # Bundle orjson (the `speedups` extra) for the durable-state / cluster
          # JSON paths; Windows amd64 ships a wheel (arm64 falls back if none).
          # The shared script round-trip-verifies it and drops a broken build,
          # so the binary falls back to stdlib json (cronstable/_json).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_orjson.sh
          # Bundle pynacl (the `push` extra); Windows ships wheels for
          # win32/amd64/arm64, so absence means a broken build. Install
          # and verify are HARD failures on this lane (a soft-fail would
          # silently ship the advertised push channel disabled).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh pynacl "pynacl>=1.5" hard
          # Bundle zeroconf (the `discovery` extra): pure Python, wheels
          # on win32/amd64/arm64, HARD failure. LGPL-2.1; in-binary
          # notice + Release source archive + public build recipe
          # (LICENSING.md).
          PIP="uv pip" PIPUNINST="uv pip uninstall" PY="uv run python" \
            sh pyinstaller/install_extra.sh zeroconf "zeroconf>=0.132" hard
          uv run pyinstaller pyinstaller/cronstable.spec
          ./dist/cronstable.exe --version      # smoke test: fails the job if the bundle is broken
          # Prove the FROZEN bundle reaches PyNaCl and zeroconf too (both
          # fail closed at config validation when they cannot import).
          ./dist/cronstable.exe --validate-config -c pyinstaller/smoke-push.yaml
          mv dist/cronstable.exe "dist/cronstable-windows-${{ matrix.arch }}.exe"
      - uses: actions/upload-artifact@v7.0.1
        with:
          name: cronstable-windows-${{ matrix.arch }}
          path: dist/cronstable-windows-${{ matrix.arch }}.exe
          if-no-files-found: error
          retention-days: 7

  # Build EVERY container image (8 distros, full published arch set) build-only,
  # no push -- the Docker half of the gate. Proves every Dockerfile still builds
  # for every arch on every commit; `docker-push` re-runs these with a push once
  # the whole gate passes. Uniform across PRs and releases (no secrets, no
  # login), so a fork PR exercises it too.
  docker:
    needs: version
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false  # one distro failing must not cancel the others
      # the canonical rows live in .github/docker-matrix.json (emitted by the
      # `version` job so `docker-push` consumes the identical list); notes on
      # per-distro platform coverage (e.g. distroless being amd64/arm64 only:
      # its base publishes no ppc64le/s390x manifest) live beside the rows.
      matrix:
        include: ${{ fromJSON(needs.version.outputs.docker-matrix) }}
    steps:
      # Shallow on purpose: CI always passes the VERSION build-arg, so
      # setuptools_scm never walks history inside the build (only a plain
      # local `docker build .` does, and that uses the builder's own git).
      - uses: actions/checkout@v7.0.1
      - uses: docker/setup-qemu-action@v4.2.0
      - uses: docker/setup-buildx-action@v4.2.0
      - name: Build image (build-only gate)
        uses: docker/build-push-action@v7.3.0
        with:
          context: .
          file: ${{ matrix.dockerfile }}
          platforms: ${{ matrix.platforms }}
          push: false
          tags: cronstable:ci-${{ matrix.distro }}
          # DEPS_REFRESH: every Dockerfile keeps its toolchain + dependency
          # layers independent of the source tree (keyed on pyproject.toml
          # plus the shared extraction helper), so on an ordinary commit the
          # QEMU-expensive dependency compiles come out of the layer cache
          # and only the project install rebuilds. On a RELEASE this arg (the
          # run id) misses those layers on purpose: a release re-resolves
          # every dependency fresh from the index, exactly the freshness
          # releases had when each push rebuilt the whole builder stage, and
          # `docker-push` below (same run, same arg) then reuses these fresh
          # layers instead of rebuilding them.
          build-args: |
            VERSION=${{ needs.version.outputs.new }}
            DEPS_REFRESH=${{ needs.version.outputs.release == 'true' && github.run_id || '' }}
          provenance: false
          # Scope the GHA cache per distro so the builds don't clobber each
          # other's layers (and warm the cache for the release `docker-push`).
          cache-from: type=gha,scope=${{ matrix.distro }}
          # Only the two long-lived branches WRITE cache; every other branch and
          # every PR reads. The GHA cache is 10 GB per repository and 8 distros
          # at mode=max is most of that on its own, so with every branch
          # exporting too the repo sat over quota (11.4 GB across 429 entries)
          # and GitHub evicted entries continuously. That eviction is what broke
          # the 1.2.31 release: an export references blobs a concurrent eviction
          # has already removed, and buildx then fails the whole build with
          # `not_found`, after every layer has already built successfully. A
          # branch that writes nothing still reads, falling back to the default
          # branch's entries, so the only thing given up here is the quota.
          #
          # The Dockerfiles' layer split (dependencies keyed on pyproject.toml
          # plus the shared extraction helper, source copied only at the
          # bottom) also calms the quota: the fat dependency layers are stable
          # across commits, so an export mostly re-references blobs that are
          # already stored instead of writing a fresh multi-GB set per push
          # the way the old source-first layout did.
          #
          # ignore-error is the second line of defence. A cache export is an
          # optimization; it must never be able to red a build that succeeded.
          cache-to: ${{ (github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main') && format('type=gha,mode=max,scope={0},ignore-error=true', matrix.distro) || '' }}

  # Paired performance benchmark. The suite in benchmarks/ runs against BOTH
  # this commit and the latest published release tag, interleaved on one
  # runner so machine noise cancels out of the comparison, and
  # benchmarks/compare.py then diffs the two sides and enforces each metric's
  # declared regression limit (a regression must also clear the metric's
  # measured round-to-round noise band to gate, so jitter cannot fail a
  # release). It runs on every event, in the same fan-out as
  # the builds. Enforcement is release-only: the `release` job needs this one,
  # so a gated regression blocks publishing, while on an ordinary commit the
  # identical comparison merely warns (a branch experiment is never blocked by
  # a perf cost its author already knows about). An intentional regression
  # ships by starting a pushed commit's SUBJECT with [perf:accept] (scanned
  # exactly like the [release] marker: subjects only, never bodies). The
  # artifact this job uploads (chart + summary + raw results) is what the
  # `release` job attaches to the GitHub Release and appends to its notes.
  perf:
    needs: version
    runs-on: ubuntu-latest
    # A budget, not a licence: the pre-additions suite measured 1609s
    # (2026-07-24, three consecutive runs within 6s of each other), and the
    # 2026-07 benchmark additions priced in at CI rates fit under this with
    # margin. bench.py prints its ten slowest benchmarks (fixtures included)
    # per run, so growth is triaged from the log before this ceiling fires.
    # A timeout here is a red X that is NOT a perf regression.
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0  # full history + tags: the baseline is the latest release tag
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Install current and baseline environments
        id: envs
        env:
          NEW_VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          uv venv --python 3.14 .venv-new
          SETUPTOOLS_SCM_PRETEND_VERSION="$NEW_VERSION" \
            uv pip install --python .venv-new/bin/python .
          # orjson, on BOTH sides (the baseline venv gets it below): the
          # binaries and Docker images ship the speedups extra, so orjson is
          # production's default JSON backend, and a perf venv without it
          # times the stdlib fallback only. Deliberately orjson alone, NOT
          # the full speedups extra: uvloop would shift every async metric's
          # baseline and most of the delta would be uvloop's own (waived in
          # benchmarks/README.md; bench.py records the flag). Not
          # best-effort: compare.py hard-fails a pairing where the two
          # sides' orjson state differs, so a one-sided install must fail
          # loudly here rather than report a backend swap as a code
          # regression.
          uv pip install --python .venv-new/bin/python orjson
          # pynacl: the push.seal_500 metric skips without it, and a
          # one-sided install is the webui/playwright dead-gate trap all
          # over again -- so it goes into BOTH venvs (the baseline install
          # is below), not best-effort.
          uv pip install --python .venv-new/bin/python pynacl
          # Web-UI benchmarks (webui.*) time renders in a headless Chromium via
          # Playwright. Install it on BOTH sides (the baseline venv is created
          # below): a metric that skips on the baseline is reported with no
          # comparison and gated: False, so installing only on the current side
          # left every webui.* gate permanently inert, a 5s render regression
          # included. Releases before the ?perf=1 hook shipped still skip on the
          # baseline for that reason, but the gate now self-heals as soon as a
          # hooked release becomes the baseline instead of staying dead.
          # Best-effort: on failure the webui.* metrics skip (recorded, never
          # failed) and the rest of the gate still runs -- but the webui ids
          # in benchmarks/expected_gated.txt then fail a RELEASE run's
          # comparison (ordinary commits warn), because a silently dead gate
          # is exactly what that file exists to catch. A transient
          # Playwright/Chromium outage on a release is a rerun, not an edit
          # to the expected list.
          uv pip install --python .venv-new/bin/python playwright || true
          .venv-new/bin/python -m playwright install --with-deps chromium \
            || echo "::warning::playwright/chromium unavailable; webui.* skip"
          git fetch --tags --force
          prev=$(git tag -l | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n1 || true)
          if [ -n "$prev" ]; then
            # The baseline side: the last release's source in a worktree,
            # installed into its own venv at its own pinned version. Both
            # sides are DRIVEN by the current checkout's benchmarks/bench.py
            # (the harness imports cronstable from whichever venv runs it), so
            # a new benchmark measures both sides and an old release simply
            # skips any API it does not have.
            git worktree add /tmp/perf-baseline "$prev"
            uv venv --python 3.14 .venv-old
            SETUPTOOLS_SCM_PRETEND_VERSION="$prev" \
              uv pip install --python .venv-old/bin/python /tmp/perf-baseline
            # The baseline side's orjson: same backend on both sides or
            # compare.py refuses the pairing (see the current-side install
            # above). Not best-effort, same reason. pynacl likewise, so
            # push.seal_500 compares as soon as a push-capable release is
            # the baseline instead of staying dead.
            uv pip install --python .venv-old/bin/python orjson pynacl
            # Same Playwright install on the baseline side, so webui.* can
            # actually be compared. The browser download above is cached
            # per-runner, so this only adds the Python package.
            uv pip install --python .venv-old/bin/python playwright || true
          else
            echo "::notice::No release tag yet; recording a baseline without a comparison."
          fi
          echo "prev=$prev" >> "$GITHUB_OUTPUT"
      - name: Run benchmarks (interleaved rounds, per tier)
        env:
          PYTHONHASHSEED: "0"
          PREV: ${{ steps.envs.outputs.prev }}
        run: |
          set -euo pipefail
          mkdir -p perf
          # Two tiers with their own round counts. The fast in-process metrics
          # get more rounds: it is cheap, it deepens the best-of-rounds
          # estimate, and it gives compare.py's robust scatter statistic
          # enough points to work with. (More rounds do NOT tighten the noise
          # band itself: the band estimates single-round scatter while the
          # comparison diffs min-of-rounds, so measured bands can even widen
          # as rounds are added.) The noisier subprocess metrics (cold
          # start, import, peak RSS) get fewer, since each round spawns
          # processes. Old then new within each round interleaves both sides
          # through the same runner weather; compare.py folds every
          # perf/{old,new}.*.json with each metric's own estimator (best-of for
          # time, median for memory).
          run_tier() {
            tier="$1"; rounds="$2"
            for round in $(seq 1 "$rounds"); do
              if [ -n "$PREV" ]; then
                .venv-old/bin/python benchmarks/bench.py --tier "$tier" \
                  --json "perf/old.$tier$round.json"
              fi
              .venv-new/bin/python benchmarks/bench.py --tier "$tier" \
                --json "perf/new.$tier$round.json"
            done
          }
          run_tier inprocess 5
          run_tier subprocess 2
      - name: Compare and gate
        env:
          RELEASE: ${{ needs.version.outputs.release }}
          NEW_VERSION: ${{ needs.version.outputs.new }}
          PREV: ${{ steps.envs.outputs.prev }}
          BEFORE: ${{ github.event.before }}
          AFTER: ${{ github.sha }}
        run: |
          set -euo pipefail
          flags=""
          if [ "$RELEASE" != "true" ]; then
            flags="--warn-only"   # ordinary commit: same comparison, warnings only
          fi
          # [perf:accept] at the START of a pushed commit SUBJECT acknowledges
          # the regression: it is still reported, but does not gate. Same
          # range and same subject-only rule as the [release] marker scan.
          zero="0000000000000000000000000000000000000000"
          if [ -z "${BEFORE:-}" ] || [ "$BEFORE" = "$zero" ] \
               || ! git rev-parse -q --verify "${BEFORE}^{commit}" >/dev/null; then
            subjects="$(git log -1 --pretty=%s "$AFTER")"
          else
            subjects="$(git log --pretty=%s "${BEFORE}..${AFTER}")"
          fi
          if printf '%s\n' "$subjects" | grep -qiE '^\[perf:accept\]'; then
            flags="$flags --accept"
            echo "::notice::[perf:accept] marker found; regressions are reported but do not gate."
          fi
          # --budgets: absolute ceilings for the headline metrics, on top of
          # the relative gate (drift across many quick releases compounds
          # under a green relative gate; the ceiling is what stops it).
          # --expected-gated: metric ids that must actually compare on both
          # sides, so a gate that silently died (baseline-side skip) fails
          # the run instead of being filed as first-release coverage.
          # Both respect --warn-only (ordinary commits warn); neither is
          # excused by [perf:accept] -- each has its own reviewed-edit
          # ritual in benchmarks/.
          if [ -z "$PREV" ]; then
            # $flags matters here too now: --budgets can gate even without a
            # baseline to diff against.
            .venv-new/bin/python benchmarks/compare.py $flags \
              --current perf/new.*.json --current-label "$NEW_VERSION" \
              --budgets benchmarks/budgets.json \
              --md perf/perf-summary.md --merged-out perf/perf-results.json
          else
            .venv-new/bin/python benchmarks/compare.py $flags \
              --baseline perf/old.*.json --current perf/new.*.json \
              --baseline-label "$PREV" --current-label "$NEW_VERSION" \
              --budgets benchmarks/budgets.json \
              --expected-gated benchmarks/expected_gated.txt \
              --md perf/perf-summary.md --svg perf/perf-chart.svg \
              --merged-out perf/perf-results.json
          fi
      # Upload even when the gate failed, so the report that explains the red
      # X is always available on the run.
      - uses: actions/upload-artifact@v7.0.1
        if: ${{ !cancelled() }}
        with:
          name: perf-report
          path: perf/
          if-no-files-found: error
          retention-days: 30

  # Developer Certificate of Origin (DCO) check. Every commit in a pull request
  # must carry a `Signed-off-by:` trailer (add one with `git commit -s`); see the
  # DCO file and CONTRIBUTING.md. PR-scoped (releases land via merge/bot commits
  # on main, which this does not police), so it is NOT in the release gate below
  # and never blocks a publish.
  dco:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0  # the full PR commit range must be walkable
      - name: Verify Signed-off-by on every PR commit
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          set -euo pipefail
          missing=0
          # The PR's own commits only (base..head), merges excluded: a
          # maintainer's merge is not a contribution needing a sign-off.
          for sha in $(git rev-list --no-merges "${BASE_SHA}..${HEAD_SHA}"); do
            if ! git show -s --format='%B' "$sha" \
                 | grep -qiE '^Signed-off-by: .+ <.+@.+>'; then
              echo "::error::Commit $(git show -s --format='%h %s' "$sha") is missing a Signed-off-by line."
              missing=1
            fi
          done
          if [ "$missing" -ne 0 ]; then
            echo "::error::DCO check failed. Sign off your commits (git commit -s). To fix an existing branch: git rebase --signoff ${BASE_SHA} then git push --force-with-lease. See CONTRIBUTING.md."
            exit 1
          fi
          echo "All PR commits carry a DCO sign-off."

  # Proprietary-package boundary guard. Builds the MIT core AND cronstable-pro
  # (pro/) and proves Pro still imports the core and keeps its entitlement gate
  # fail-closed. The whole point of the split is that premium code depends on the
  # core's public API without living inside the MIT package. This runs on every
  # push and PR but is NOT in the release gate below; the MIT core ships
  # independently of the proprietary package's health.
  pro:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0  # setuptools_scm needs history to version the core
      - uses: actions/setup-python@v7.0.0
        with:
          python-version: '3.14'
      - uses: astral-sh/setup-uv@v9.0.0
        with:
          version: "0.12.1"
      - name: Build core + pro, prove the boundary, run pro's tests
        run: |
          set -euo pipefail
          uv venv --python 3.14
          uv pip install .              # the MIT core (root), from local source
          uv pip install "./pro[dev]"   # cronstable-pro (its core dep is satisfied)
          uv run python -c "import cronstable_pro; print('pro', cronstable_pro.__version__, '/ core', cronstable_pro.core_version())"
          uv run pytest pro/tests -q

  # ---------------------------------------------------------------------------
  # Publish. Runs ONLY on a release, and ONLY after every gate job above has
  # succeeded. Skip-propagation makes docker-push/homebrew skip automatically
  # when `release` is skipped on an ordinary commit (do NOT add always()).
  # ---------------------------------------------------------------------------

  release:
    needs:
      - version
      - tox
      - tox-static
      - licenses
      - dist
      - binaries
      - binaries-container
      - binaries-macos
      - binaries-windows
      - docker
      - perf
    if: needs.version.outputs.release == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write   # push the tag and create the GitHub Release
      id-token: write   # PyPI Trusted Publishing (OIDC)
    steps:
      - uses: actions/checkout@v7.0.1
        with:
          fetch-depth: 0

      # The wheel + sdist built (and twine-checked) by `dist`: publish these
      # exact bytes rather than rebuilding.
      - name: Download distributions
        uses: actions/download-artifact@v8.0.1
        with:
          name: dist
          path: dist

      - name: Publish to PyPI (Trusted Publishing)
        uses: pypa/gh-action-pypi-publish@v1.14.2
        with:
          # Idempotent re-runs: the publish precedes the tag/Release below, so if
          # a later step fails (e.g. the tag push) the version is already on PyPI.
          # skip-existing makes re-running the workflow a no-op on the upload
          # instead of a hard "file already exists" failure, so the tag + Release
          # can be completed on a retry without burning the version.
          skip-existing: true

      # Everything below runs only after PyPI has accepted the upload.
      - name: Tag the release
        env:
          NEW: ${{ needs.version.outputs.new }}
          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
        run: |
          set -euo pipefail
          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git tag -a "$NEW" -m "Release $NEW"
          # The default GITHUB_TOKEN is the GitHub Actions *App*, and GitHub
          # forbids an App from pushing a ref that creates/updates any file under
          # .github/workflows/ unless the token carries the `workflows` scope --
          # which is NOT grantable to GITHUB_TOKEN. This release tag points at a
          # commit that may itself modify this workflow, so pushing it with
          # GITHUB_TOKEN is rejected. Push instead with RELEASE_TOKEN -- a PAT or
          # GitHub App token with `workflow` scope (fine-grained: Contents +
          # Workflows: write) -- exactly like the cross-repo Homebrew push uses
          # HOMEBREW_TAP_TOKEN. If it is unset we fall back to GITHUB_TOKEN with a
          # warning (works only when the tagged commit doesn't touch
          # .github/workflows/).
          if [ -n "${RELEASE_TOKEN:-}" ]; then
            git push "https://x-access-token:${RELEASE_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "refs/tags/$NEW"
          else
            echo "::warning::RELEASE_TOKEN not set; pushing the tag with the default GITHUB_TOKEN. This FAILS if the tagged commit modifies .github/workflows/ -- set RELEASE_TOKEN (Contents + Workflows: write) to fix."
            git push origin "refs/tags/$NEW"
          fi

      # Pull in every per-arch binary the gate built (fast + slow). The pattern
      # is broad and flattens them into ./binaries; the CI-only macOS 26 assets
      # (cronstable-macos26-*) land here too but are neither hashed nor attached
      # below (the lists are explicit).
      - name: Download release binaries
        uses: actions/download-artifact@v8.0.1
        with:
          path: binaries
          pattern: cronstable-*
          merge-multiple: true

      # One SHA256SUMS over the dist + every SHIPPED binary (bare filenames, so
      # `sha256sum -c` works from any directory). Enumerated explicitly -- a
      # `cronstable-*` glob would fold the CI-only macOS 26 binaries into the
      # shipped manifest.
      - name: Generate SHA256SUMS
        run: |
          set -euo pipefail
          work="$(mktemp -d)"
          cp dist/*.whl dist/*.tar.gz \
             binaries/cronstable-linux-amd64 binaries/cronstable-linux-arm64 \
             binaries/cronstable-linux-i686 binaries/cronstable-linux-armv7 \
             binaries/cronstable-linux-ppc64le binaries/cronstable-linux-s390x \
             binaries/cronstable-linux-riscv64 \
             binaries/cronstable-linux-amd64-musl binaries/cronstable-linux-arm64-musl \
             binaries/cronstable-linux-i686-musl binaries/cronstable-linux-armv7-musl \
             binaries/cronstable-linux-ppc64le-musl binaries/cronstable-linux-s390x-musl \
             binaries/cronstable-linux-riscv64-musl binaries/cronstable-linux-armv6-musl \
             binaries/cronstable-macos-amd64 binaries/cronstable-macos-arm64 \
             binaries/cronstable-windows-amd64.exe binaries/cronstable-windows-arm64.exe \
             "$work"/
          ( cd "$work" && sha256sum -- * ) > SHA256SUMS
          cat SHA256SUMS

      # The perf gate's output for THIS run: the markdown summary the notes
      # append, the merged raw results for the record, and the chart (kept in
      # this artifact only, never attached to the Release).
      - name: Download performance report
        uses: actions/download-artifact@v8.0.1
        with:
          name: perf-report
          path: perf

      - name: Build release notes from HISTORY.md
        env:
          NEW: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          # Pull this version's section out of HISTORY.md (everything between its
          # own "## X.Y.Z" header and the next "## " header), dropping leading
          # blank lines. The header is matched on whitespace-split fields
          # ($1 == "##", $2 == the exact version) so it hits whether the heading
          # is still bare ("## 1.2.9") or already dated ("## 1.2.9 (2026-07-07)").
          # The exact $2 match also keeps 1.2.1 from swallowing 1.2.10's section.
          awk -v ver="$NEW" '
            $1 == "##" && $2 == ver { cap = 1; next }
            cap && /^## / { exit }
            cap { print }
          ' HISTORY.md | sed '/./,$!d' > release-notes.md
          if [ -s release-notes.md ]; then
            echo "::notice::Using HISTORY.md notes for $NEW."
          else
            echo "::warning::No HISTORY.md section for $NEW; release notes will be auto-generated only."
          fi
          # Append the perf comparison (gate verdict + full table) below the
          # curated notes. Text only: the perf job passes no --img-url, so the
          # body embeds no <img> for perf-chart.svg. An image in a release body
          # is refetched by every render of it (the tag page, the /releases
          # index, the releases.atom feed release-watching bots poll) because
          # the counted /releases/download/ hop is Cache-Control: no-cache, and
          # it cannot even display: GitHub signs asset URLs with
          # response-content-type=application/octet-stream plus
          # Content-Disposition: attachment, and browsers do not sniff SVG in
          # an <img>, so it only ever rendered as its alt text.
          {
            echo ""
            cat perf/perf-summary.md
          } >> release-notes.md

      # LGPL source offer for the bundled python-zeroconf: attach its sdist
      # (same requirement the binary lanes installed, resolved within this
      # run) plus the notice file, so the Release page itself provides the
      # license text and equivalent access to the library source next to
      # the binaries that bundle it. --no-deps on purpose: only zeroconf is
      # LGPL; its dependencies are permissive and covered by the licenses
      # gate. See LICENSING.md.
      - name: Fetch python-zeroconf source (LGPL source offer)
        run: |
          set -euo pipefail
          mkdir -p third-party
          python3 -m pip download "zeroconf>=0.132" --no-deps --no-binary :all: -d third-party
          cp cronstable/licenses/THIRD-PARTY-NOTICES.txt third-party/
          ls -l third-party

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v3.0.2
        with:
          tag_name: ${{ needs.version.outputs.new }}
          name: ${{ needs.version.outputs.new }}
          # The curated HISTORY.md section becomes the body; with
          # generate_release_notes it is prepended above GitHub's auto-generated
          # "What's Changed" / Full Changelog compare link.
          body_path: release-notes.md
          generate_release_notes: true
          # Every shipped binary + the single SHA256SUMS, attached in one shot
          # (no later attach step, so nothing ever fights immutable-release
          # protection).
          # The benchmark report, listed by name rather than as a perf/perf-*
          # glob so that perf-chart.svg (downloaded into perf/ with the rest of
          # the perf-report artifact) stays OFF the release: as a release asset
          # it collected more downloads than every binary combined, because
          # anything that rendered the notes fetched it. Both files here are
          # written on every run, including the first release that has no
          # baseline to diff against. The chart ships in the perf-report
          # workflow artifact.
          files: |
            SHA256SUMS
            perf/perf-summary.md
            perf/perf-results.json
            third-party/THIRD-PARTY-NOTICES.txt
            third-party/zeroconf-*.tar.gz
            dist/*.whl
            dist/*.tar.gz
            binaries/cronstable-linux-amd64
            binaries/cronstable-linux-arm64
            binaries/cronstable-linux-i686
            binaries/cronstable-linux-armv7
            binaries/cronstable-linux-ppc64le
            binaries/cronstable-linux-s390x
            binaries/cronstable-linux-riscv64
            binaries/cronstable-linux-amd64-musl
            binaries/cronstable-linux-arm64-musl
            binaries/cronstable-linux-i686-musl
            binaries/cronstable-linux-armv7-musl
            binaries/cronstable-linux-ppc64le-musl
            binaries/cronstable-linux-s390x-musl
            binaries/cronstable-linux-riscv64-musl
            binaries/cronstable-linux-armv6-musl
            binaries/cronstable-macos-amd64
            binaries/cronstable-macos-arm64
            binaries/cronstable-windows-amd64.exe
            binaries/cronstable-windows-arm64.exe

  # Build + push the multi-arch container images at the just-released version.
  # Runs after `release` (so the tag it checks out exists) and is thus gated on
  # the whole build+test gate, including the `docker` build-only job, via
  # `needs: release`. Pushes one image per distro to GHCR (and Docker Hub when
  # the DOCKERHUB_* secrets are set); the Debian image owns the bare
  # `latest`/`<version>` tags, the variants get `-<distro>` suffixes.
  docker-push:
    needs: [version, release]
    if: needs.version.outputs.release == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write   # push to GHCR
    strategy:
      fail-fast: false
      # the same canonical rows the build-only `docker` gate ran, from
      # .github/docker-matrix.json via the `version` job: what was gated is
      # exactly what is pushed, suffixes included.
      matrix:
        include: ${{ fromJSON(needs.version.outputs.docker-matrix) }}
    steps:
      - name: Resolve registries
        id: registries
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
          REPO: ${{ github.repository }}
        run: |
          set -euo pipefail
          images="ghcr.io/${REPO,,}"   # GHCR image names must be lowercase
          dockerhub=false
          # Require BOTH secrets before enabling Docker Hub. Gating on the
          # username alone would, in the half-configured case, still try the
          # Docker Hub login -- which fails and aborts the whole job, taking the
          # otherwise-safe GHCR push down with it. Demanding both degrades
          # cleanly to GHCR-only.
          if [ -n "${DOCKERHUB_USERNAME:-}" ] && [ -n "${DOCKERHUB_TOKEN:-}" ]; then
            images="${images}"$'\n'"docker.io/${DOCKERHUB_USERNAME}/cronstable"
            dockerhub=true
          fi
          {
            echo "dockerhub=$dockerhub"
            echo "images<<EOF"
            echo "$images"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      # Shallow on purpose: the VERSION build-arg pins the version, so
      # setuptools_scm never walks history inside the build.
      - uses: actions/checkout@v7.0.1
        with:
          ref: ${{ needs.version.outputs.new }}  # the tag `release` just pushed

      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@v6.2.0
        with:
          images: ${{ steps.registries.outputs.images }}
          # The distro suffix (e.g. `-alpine`) is appended to every tag; it is
          # empty for Debian, which therefore owns the bare `latest`/`<version>`.
          flavor: |
            latest=false
            suffix=${{ matrix.suffix }}
          tags: |
            type=raw,value=${{ needs.version.outputs.new }}
            type=raw,value=latest
            # Explicit -debian alias so the default base is pinnable by name too
            # (latest-debian / <version>-debian), mirroring the other variants.
            type=raw,value=${{ needs.version.outputs.new }}-debian,enable=${{ matrix.distro == 'debian' }}
            type=raw,value=latest-debian,enable=${{ matrix.distro == 'debian' }}

      - name: Log in to GHCR
        uses: docker/login-action@v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ github.token }}

      - name: Log in to Docker Hub
        if: steps.registries.outputs.dockerhub == 'true'
        uses: docker/login-action@v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - uses: docker/setup-qemu-action@v4.2.0
      - uses: docker/setup-buildx-action@v4.2.0

      - name: Build and push
        uses: docker/build-push-action@v7.3.0
        with:
          context: .
          file: ${{ matrix.dockerfile }}
          platforms: ${{ matrix.platforms }}
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          # DEPS_REFRESH matches the gate `docker` job's release-run value
          # (this job only runs on releases, where the gate passed the run
          # id), so the freshly resolved dependency layers built minutes ago
          # in this same run are what get pushed, not older cached ones.
          build-args: |
            VERSION=${{ needs.version.outputs.new }}
            DEPS_REFRESH=${{ github.run_id }}
          provenance: false
          # Reuse the layers the gate `docker` job just cached (same per-distro
          # scope), so this is mostly manifest assembly + push.
          cache-from: type=gha,scope=${{ matrix.distro }}
          # Read-only on purpose. The gate `docker` job exported these exact
          # layers to this exact scope minutes ago in this same run, so an
          # export here rewrites bytes that are already cached, at the cost of
          # more pressure on a 10 GB quota whose overflow is what broke the
          # previous release (see that job for the full story). This is also the
          # publish path, the worst possible place to keep a step that can fail
          # on something as incidental as a cache write.
          cache-to: ""

  # Push the just-released version to the Homebrew tap (ptweezy/homebrew-tap) so
  # `brew install ptweezy/tap/cronstable` and `brew upgrade` track releases with
  # no manual step. Re-renders Formula/cronstable.rb from the template in this
  # repo, pinning each binary's SHA256 from the SHA256SUMS the `release` job
  # published (it covers the macOS + linux glibc amd64/arm64 sums this formula
  # needs).
  #
  # Cross-repo pushes need a token the default GITHUB_TOKEN can't provide: set a
  # repo secret HOMEBREW_TAP_TOKEN to a PAT (fine-grained, Contents: read/write
  # on ptweezy/homebrew-tap is enough). If it is unset the job fails loudly
  # rather than leaving the tap stale (the step below says why); this header
  # described the older warn-and-skip behaviour long after it changed.
  homebrew:
    needs: [version, release]
    if: needs.version.outputs.release == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1    # for the formula template + render script

      - name: Update Homebrew tap formula
        env:
          TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
          VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          if [ -z "${TAP_TOKEN:-}" ]; then
            # A release MUST update the tap. Skipping silently is exactly how the
            # yacron2 -> cronstable rename shipped for several versions without
            # ever publishing a cronstable formula -- the tap froze while every
            # release stayed green. Fail loudly so a stale tap can't hide behind
            # a successful run.
            echo "::error::HOMEBREW_TAP_TOKEN is not set; cannot update the Homebrew tap. Add it as a repo secret (fine-grained PAT with Contents: read/write on ptweezy/homebrew-tap) and re-run this release." >&2
            exit 1
          fi

          # Fetch the checksums this release just published (retry: the asset can
          # lag the API by a few seconds after the release is created).
          curl -fsSL --retry 5 --retry-all-errors --retry-delay 5 -o SHA256SUMS \
            "https://github.com/ptweezy/cronstable/releases/download/${VERSION}/SHA256SUMS"

          # Retried through a function, not inline: the helper names the failed
          # command in its warning, and the clone URL carries the tap token.
          # The rm makes a retry idempotent (git refuses a non-empty target, so
          # a half-finished clone would fail every later attempt).
          . .github/scripts/retry.sh
          clone_tap() {
            rm -rf tap
            git clone --depth 1 \
              "https://x-access-token:${TAP_TOKEN}@github.com/ptweezy/homebrew-tap.git" tap
          }
          retry 5 clone_tap
          mkdir -p tap/Formula
          bash packaging/homebrew/render-formula.sh \
            "$VERSION" SHA256SUMS packaging/homebrew/cronstable.rb.tmpl > tap/Formula/cronstable.rb

          cd tap
          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          # Stage FIRST, then compare the index: a plain `git diff` ignores
          # untracked files, so on the formula's first publication it reported
          # "no changes" and the job exited green without ever committing --
          # the tap stayed empty while every release passed.
          git add Formula/cronstable.rb
          if git diff --cached --quiet; then
            echo "Formula already current for ${VERSION}."
            exit 0
          fi
          git commit -m "cronstable ${VERSION}"
          git push

  # Update the winget manifest (ptweezy.cronstable) in microsoft/winget-pkgs so
  # `winget install ptweezy.cronstable` / `winget upgrade` track releases with no
  # manual step. Unlike the Homebrew formula, there is no template to render here:
  # wingetcreate fetches the previous manifest from winget-pkgs itself, bumps the
  # version, and re-detects each installer's architecture straight from the PE
  # header of the downloaded .exe (not from the filename), then opens a PR.
  # windows-latest is required -- wingetcreate.exe is a native Windows tool.
  #
  # Cross-repo PRs need a token the default GITHUB_TOKEN can't provide: set a repo
  # secret WINGET_TOKEN to a PAT (classic, public_repo scope is enough) that can
  # fork microsoft/winget-pkgs and open a PR under that account. Normally an
  # unset token must fail loudly rather than silently leave the manifest stale
  # (see the homebrew job above for why silent-skip is the wrong default here);
  # it currently exits 0 instead, as part of the temporary allowance below.
  #
  # TEMPORARY: this job is warning-only until the initial ptweezy.cronstable
  # submission PR is merged into microsoft/winget-pkgs. `wingetcreate update`
  # fetches the EXISTING manifest to bump it, so it fails until the package
  # exists there.
  #
  # Once that first PR merges, ALL THREE suppressions have to come off, or the
  # job goes on passing over a genuinely broken manifest update. A silent-skip
  # default is how the homebrew tap froze across several releases while every
  # run stayed green (see that job's own note above), which is the failure mode
  # a partial restore here would recreate:
  #   1. `continue-on-error: true` on the job (below). This one dominates: while
  #      it is set, neither of the others can fail the release. They do still
  #      flip the job's own recorded conclusion in the run view, which is the
  #      only signal a partial restore leaves.
  #   2. the missing-token branch's `exit 0` (restore it to `exit 1`).
  #   3. the `if ! ./wingetcreate.exe update ...; then ... exit 0; fi` wrapper
  #      around the update itself: delete the wrapper and let the command's own
  #      exit status fail the step under `set -e`. This is the one with no
  #      other trace, and it survives removing 1 and 2.
  winget:
    needs: [version, release]
    if: needs.version.outputs.release == 'true'
    runs-on: windows-latest
    continue-on-error: true
    defaults:
      run:
        shell: bash
    steps:
      - name: Update winget manifest
        env:
          WINGET_TOKEN: ${{ secrets.WINGET_TOKEN }}
          VERSION: ${{ needs.version.outputs.new }}
        run: |
          set -euo pipefail
          if [ -z "${WINGET_TOKEN:-}" ]; then
            echo "::warning::WINGET_TOKEN is not set; skipping winget manifest update. Add it as a repo secret (a GitHub PAT with public_repo scope) to enable it." >&2
            exit 0
          fi
          curl -fsSL --retry 5 --retry-all-errors --retry-delay 5 -o wingetcreate.exe \
            https://github.com/microsoft/winget-create/releases/latest/download/wingetcreate.exe
          if ! ./wingetcreate.exe update ptweezy.cronstable \
            --version "$VERSION" \
            --urls \
              "https://github.com/ptweezy/cronstable/releases/download/${VERSION}/cronstable-windows-amd64.exe" \
              "https://github.com/ptweezy/cronstable/releases/download/${VERSION}/cronstable-windows-arm64.exe" \
            --submit --no-open --token "$WINGET_TOKEN" \
            --prtitle "New version: ptweezy.cronstable version ${VERSION}"; then
            echo "::warning::wingetcreate update failed (expected until the initial ptweezy.cronstable PR is merged into microsoft/winget-pkgs). Treating as non-fatal for now." >&2
            exit 0
          fi

  # ---------------------------------------------------------------------------
  # Docs. Runs on an ordinary commit and is NOT gated on the build+test matrix:
  # a wiki page is not a build artifact, so it neither waits on a release nor
  # lets a flaky emulated arch hold up a typo fix.
  # ---------------------------------------------------------------------------

  # Publish wiki/ to this repository's GitHub wiki. The wiki is a SEPARATE git
  # repo (<repo>.wiki.git), so committing wiki/ here has never updated the live
  # wiki -- that was a manual clone-copy-push, and it drifted exactly the way an
  # unautomated step always does (7 pages, some a week stale, when this job was
  # written). wiki/ is the source of truth; the wiki is the render target (the
  # pages use ~460 bare `[Page](Page)` wiki links, which ONLY resolve there).
  #
  # Publishes from `develop`, not `main`: develop is the default branch and
  # where wiki/ is edited, and the pages hardcode /blob/develop/ links and
  # raw.githubusercontent.com/.../develop/ screenshots -- the wiki documents
  # develop by construction. Syncing from both would also race: `concurrency` is
  # keyed per branch, so a develop push and a main merge are NOT serialized
  # against each other and their wiki pushes would collide.
  #
  # GITHUB_TOKEN with `contents: write` can push a repo's OWN wiki -- no PAT.
  # The widespread "wikis need a PAT" advice traces to one archived action's
  # README, last touched the day BEFORE GitHub shipped configurable
  # GITHUB_TOKEN permissions (2021-04-20); it has been wrong ever since. A PAT
  # is only needed for a wiki in a DIFFERENT repo -- which is why the Homebrew
  # tap push above needs HOMEBREW_TAP_TOKEN and this job needs no secret at all.
  wiki:
    # The repository guard is not redundant: a fork has its OWN develop, and a
    # fork's wiki is uninitialized (a wiki repo does not exist until someone
    # creates a page), so `<fork>/cronstable.wiki` 404s and the checkout fails.
    # Every other job in this pipeline is fork-clean, so without this the wiki
    # job would be a permanent red X on every fork's develop push.
    if: github.event_name == 'push' && github.ref == 'refs/heads/develop' && github.repository == 'ptweezy/cronstable'
    runs-on: ubuntu-latest
    permissions:
      # The one grant that allows pushing the wiki. GitHub's docs never mention
      # wikis under `contents`, but staff confirm it and both maintained wiki
      # actions default to GITHUB_TOKEN. Nothing in THIS repo is written.
      contents: write
    steps:
      - uses: actions/checkout@v7.0.1    # for the wiki/ page sources
      - uses: actions/checkout@v7.0.1    # the wiki is its own repo; its default branch is always master
        with:
          repository: ${{ github.repository }}.wiki
          path: .wiki

      - name: Publish wiki/ to the GitHub wiki
        env:
          SHA: ${{ github.sha }}
        run: |
          set -euo pipefail

          # Mirror, so a page deleted from wiki/ is deleted from the wiki too.
          # The corollary is deliberate: a page created in the wiki's web UI is
          # transient and this job will remove it. Edit wiki/ and let CI publish.
          mirror() {
            find .wiki -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
            cp -R wiki/. .wiki/
          }

          git -C .wiki config user.name  "github-actions[bot]"
          git -C .wiki config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          # The wiki accepts web-UI edits and two develop pushes can overlap
          # before cancel-in-progress lands, so a push CAN lose a race. The
          # commit is a pure snapshot of wiki/, so there is nothing to rebase --
          # re-mirror onto the new tip and retry instead of reddening a docs run.
          for attempt in 1 2 3; do
            git -C .wiki fetch -q origin master
            git -C .wiki reset -q --hard origin/master
            mirror

            # Stage FIRST, then compare the index: a plain `git diff` ignores
            # untracked files, so a brand-new page would report "no changes" and
            # this job would exit green having published nothing -- the same way
            # the tap above stayed empty through green releases.
            git -C .wiki add -A
            if git -C .wiki diff --cached --quiet; then
              echo "Wiki already current for ${SHA:0:7}."
              exit 0
            fi

            # Print the change set: a mirror deletes, and a deletion must never
            # be silent in the log.
            git -C .wiki diff --cached --name-status

            git -C .wiki commit -q -m "Sync wiki from ${SHA:0:7}"
            if git -C .wiki push -q origin HEAD:master; then
              echo "::notice::Wiki published from ${SHA:0:7}."
              exit 0
            fi
            echo "::warning::Wiki push rejected (attempt ${attempt}/3); re-mirroring onto the new tip."
          done

          echo "::error::Could not push the wiki after 3 attempts; the wiki repo is being written concurrently. Re-run this job." >&2
          exit 1