release.yml

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Release version (e.g. 1.0.0 or v1.0.0)"
        required: true
        type: string
      target:
        description: "Release target"
        required: true
        type: choice
        default: testpypi
        options:
          - testpypi
          - production
      replace_release_assets:
        description: "Replace assets on an already-published GitHub Release (changes their SHA256s; never the default)"
        required: false
        type: boolean
        default: false
      already_published_channels:
        description: "Optional comma-separated channel names preserved from a prior release run for this exact version"
        required: false
        default: ""
        type: string

permissions:
  contents: write

env:
  RELEASE_ARTIFACT_MANIFEST: release/publish-artifacts.toml

jobs:
  gate-and-tag:
    runs-on: ubuntu-latest
    outputs:
      release_tag: ${{ steps.meta.outputs.release_tag }}
      release_version: ${{ steps.meta.outputs.release_version }}
      release_target: ${{ steps.meta.outputs.release_target }}
      build_ref: ${{ steps.release-ref.outputs.build_ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Normalize version input
        id: meta
        shell: bash
        run: |
          set -euo pipefail
          raw='${{ github.event.inputs.version }}'
          target='${{ github.event.inputs.target }}'
          tag="$raw"
          [[ "$tag" == v* ]] || tag="v${tag}"
          if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "Invalid version: '$raw' (expected X.Y.Z or vX.Y.Z)" >&2
            exit 1
          fi
          if [[ "$target" != "testpypi" && "$target" != "production" ]]; then
            echo "Invalid target: '$target' (expected testpypi or production)" >&2
            exit 1
          fi
          echo "release_tag=$tag" >> "$GITHUB_OUTPUT"
          echo "release_version=${tag#v}" >> "$GITHUB_OUTPUT"
          echo "release_target=$target" >> "$GITHUB_OUTPUT"

      - name: Read build plan from release manifest
        id: build_plan
        shell: bash
        run: |
          set -euo pipefail
          plan="$(python3 .github/scripts/release_artifacts.py build-plan --manifest "${RELEASE_ARTIFACT_MANIFEST}")"
          {
            echo "workspace_toml=$(jq -r '.workspace_toml' <<<"${plan}")"
            echo "has_crates=$(jq -r '.has_crates' <<<"${plan}")"
          } >> "$GITHUB_OUTPUT"

      - name: Verify requested version matches workspace
        run: |
          python3 .github/scripts/release_artifacts.py verify-version \
            --manifest "${RELEASE_ARTIFACT_MANIFEST}" \
            --workspace-toml '${{ steps.build_plan.outputs.workspace_toml }}' \
            --version '${{ steps.meta.outputs.release_version }}'

      - name: Verify release version lockstep
        run: |
          python3 .github/scripts/release_artifacts.py verify-version-lockstep \
            --manifest "${RELEASE_ARTIFACT_MANIFEST}" \
            --workspace-toml '${{ steps.build_plan.outputs.workspace_toml }}'
          python3 .github/scripts/go_native_module.py verify-version-lockstep \
            --config release/go-native-module.toml \
            --workspace-toml '${{ steps.build_plan.outputs.workspace_toml }}'

      - name: Run release gate
        id: release_gate
        env:
          ALREADY_PUBLISHED_CHANNELS: ${{ inputs.already_published_channels }}
        run: .github/scripts/release_gate.sh final origin/main "release-candidate-${{ steps.meta.outputs.release_tag }}" '${{ steps.meta.outputs.release_version }}' "${RELEASE_ARTIFACT_MANIFEST}" '${{ steps.build_plan.outputs.workspace_toml }}' "${ALREADY_PUBLISHED_CHANNELS}"

      - name: Ensure tag is correct or create it
        id: release-ref
        shell: bash
        run: |
          set -euo pipefail
          git fetch origin --prune --tags
          tag='${{ steps.meta.outputs.release_tag }}'
          target='${{ steps.meta.outputs.release_target }}'
          main_sha='${{ steps.release_gate.outputs.release_sha }}'
          git rev-parse --verify "${main_sha}^{commit}" >/dev/null
          candidate_tag="release-candidate-${tag}"
          if [[ "$target" == "production" ]]; then
            if git ls-remote --exit-code --refs origin "refs/tags/${tag}" >/dev/null; then
              remote_tag_sha="$(git rev-parse "refs/tags/${tag}^{commit}")"
              if ! git merge-base --is-ancestor "$remote_tag_sha" origin/main; then
                echo "Tag ${tag} exists at ${remote_tag_sha} but is not an ancestor of origin/main (${main_sha})" >&2
                exit 1
              fi
              if ! git merge-base --is-ancestor "$candidate_tag" "$remote_tag_sha"; then
                echo "Tag ${tag} exists at ${remote_tag_sha} but does not descend from ${candidate_tag}" >&2
                exit 1
              fi
              echo "Tag ${tag} already exists at verified ancestor ${remote_tag_sha}; reusing immutable tag while building from origin/main (${main_sha})"
            else
              git tag "$tag" "$main_sha"
              git push origin "$tag"
            fi
          else
            echo "Rehearsal mode: validating release tag ${tag} locally only; not pushing any tag to origin"
          fi
          echo "build_ref=$main_sha" >> "$GITHUB_OUTPUT"

  build:
    needs: [gate-and-tag, release-plan]
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.release-plan.outputs.release_target_matrix) }}
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.release-plan.outputs.rust_toolchain }}
          targets: ${{ matrix.target }}

      - name: Ensure cross-compilation target
        run: rustup target add ${{ matrix.target }}

      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ matrix.target }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}

      - name: Build release binaries
        shell: bash
        run: |
          set -euo pipefail
          bin_args="$(python3 .github/scripts/release_artifacts.py cargo-build-bin-args --manifest "${RELEASE_ARTIFACT_MANIFEST}")"
          cargo build --release --target ${{ matrix.target }} ${bin_args}

      - name: Package manifest-declared release archive
        shell: bash
        run: |
          set -euo pipefail
          python3 - <<'PY'
          import json
          import os
          from pathlib import Path
          import shutil
          import subprocess
          import tarfile
          import zipfile

          target_name = "${{ matrix.target }}"
          version = "${{ needs.gate-and-tag.outputs.release_version }}"
          config = json.loads(
              subprocess.check_output(
                  [
                      "python3",
                      ".github/scripts/release_artifacts.py",
                      "release-package-config",
                      "--manifest",
                      os.environ["RELEASE_ARTIFACT_MANIFEST"],
                      "--target",
                      target_name,
                  ],
                  text=True,
              )
          )
          project = config["project"]
          target = config["target"]
          stage = Path(f"{project['archive_prefix']}_{version}_{target_name}")
          if stage.exists():
              shutil.rmtree(stage)
          (stage / "bin").mkdir(parents=True)
          for binary in config["binaries"]:
              filename = binary["name"] + (".exe" if "windows" in target_name else "")
              shutil.copy2(Path("target") / target_name / "release" / filename, stage / "bin" / filename)
              for bundled_path in binary.get("bundled_paths", []):
                  source = Path(bundled_path["source"])
                  destination = stage / bundled_path["destination"]
                  destination.parent.mkdir(parents=True, exist_ok=True)
                  shutil.copytree(source, destination, dirs_exist_ok=True)
          archive = Path(f"{stage}.{target['archive']}")
          if target["archive"] == "tar.gz":
              with tarfile.open(archive, "w:gz") as output:
                  output.add(stage, arcname=stage.name)
          elif target["archive"] == "zip":
              with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as output:
                  for item in stage.rglob("*"):
                      if item.is_file():
                          output.write(item, item.relative_to(stage.parent))
          else:
              raise SystemExit(f"unsupported archive type: {target['archive']}")
          with Path(os.environ["GITHUB_ENV"]).open("a", encoding="utf-8") as env:
              env.write(f"ARCHIVE={archive}\n")
          PY

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.target }}
          path: ${{ env.ARCHIVE }}

  publish:
    if: ${{ needs.gate-and-tag.outputs.release_target == 'production' && needs.release-plan.outputs.has_crates == 'true' }}
    needs: [gate-and-tag, release-plan]
    runs-on: ubuntu-latest
    environment: crates-io
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ needs.release-plan.outputs.rust_toolchain }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Publish crates in order (idempotent)
        env:
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
        shell: bash
        run: |
          set -euo pipefail
          version='${{ needs.gate-and-tag.outputs.release_version }}'
          contracts="$(dirname "${RELEASE_ARTIFACT_MANIFEST}")/publish-channel-contracts.toml"

          # Exact, contract-derived already-published lookup (200/404 state
          # machine); fuzzy registry text search is index-lagged and ranked.
          crate_exists() {
            local crate="$1"
            local version="$2"
            local url status
            url="$(python3 .github/scripts/release_artifacts.py public-registry-inquiry-plan \
              --contracts "${contracts}" --channel crates_io --name "${crate}" --version "${version}" \
              | jq -r '.checks[0].version_lookup_url')"
            state="$(python3 .github/scripts/release_artifacts.py registry-status --url "${url}")"
            case "${state}" in
              published) return 0 ;;
              absent) return 1 ;;
              *)
                echo "crates.io state for ${crate}@${version} is indeterminate (state ${state})" >&2
                exit 1
                ;;
            esac
          }

          publish_if_missing() {
            local crate="$1"
            local wait_seconds="${2:-0}"
            if crate_exists "$crate" "$version"; then
              echo "${crate} ${version} already published; skipping"
              return 0
            fi
            cargo publish -p "$crate" --locked
            if [[ "$wait_seconds" != "0" ]]; then
              sleep "$wait_seconds"
            fi
          }

          while IFS='|' read -r package wait_secs; do
            publish_if_missing "$package" "${wait_secs:-0}"
          done < <(python3 .github/scripts/release_artifacts.py list-publish-plan --manifest "${RELEASE_ARTIFACT_MANIFEST}")

  release-plan:
    needs: gate-and-tag
    runs-on: ubuntu-latest
    outputs:
      release_target_matrix: ${{ steps.manifest.outputs.release_target_matrix }}
      python_wheel_matrix: ${{ steps.manifest.outputs.python_wheel_matrix }}
      python_sdist_matrix: ${{ steps.manifest.outputs.python_sdist_matrix }}
      has_crates: ${{ steps.manifest.outputs.has_crates }}
      has_python_wheels: ${{ steps.manifest.outputs.has_python_wheels }}
      has_python_sdists: ${{ steps.manifest.outputs.has_python_sdists }}
      python_upload_tool: ${{ steps.manifest.outputs.python_upload_tool }}
      rust_toolchain: ${{ steps.manifest.outputs.rust_toolchain }}
      workspace_toml: ${{ steps.manifest.outputs.workspace_toml }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}
      - id: manifest
        name: Read Python distribution matrices from release manifest
        shell: bash
        run: |
          set -euo pipefail
          echo "release_target_matrix=$(python3 .github/scripts/release_artifacts.py release-target-matrix --manifest "${RELEASE_ARTIFACT_MANIFEST}")" >> "$GITHUB_OUTPUT"
          echo "python_wheel_matrix=$(python3 .github/scripts/release_artifacts.py python-wheel-matrix --manifest "${RELEASE_ARTIFACT_MANIFEST}")" >> "$GITHUB_OUTPUT"
          echo "python_sdist_matrix=$(python3 .github/scripts/release_artifacts.py python-sdist-matrix --manifest "${RELEASE_ARTIFACT_MANIFEST}")" >> "$GITHUB_OUTPUT"
          plan="$(python3 .github/scripts/release_artifacts.py build-plan --manifest "${RELEASE_ARTIFACT_MANIFEST}")"
          {
            echo "has_crates=$(jq -r '.has_crates' <<<"${plan}")"
            echo "has_python_wheels=$(jq -r '.has_python_wheels' <<<"${plan}")"
            echo "has_python_sdists=$(jq -r '.has_python_sdists' <<<"${plan}")"
            echo "python_upload_tool=$(jq -r '.python_upload_tool' <<<"${plan}")"
            echo "rust_toolchain=$(jq -r '.rust_toolchain' <<<"${plan}")"
            echo "workspace_toml=$(jq -r '.workspace_toml' <<<"${plan}")"
          } >> "$GITHUB_OUTPUT"

  build-python-wheels:
    if: ${{ needs.release-plan.outputs.has_python_wheels == 'true' }}
    needs: [gate-and-tag, release-plan]
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.release-plan.outputs.python_wheel_matrix) }}
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}
      - uses: ./.github/actions/setup-python-release-build
        with:
          release_ref: ${{ needs.gate-and-tag.outputs.build_ref }}
          release_version: ${{ needs.gate-and-tag.outputs.release_version }}
          pyproject: ${{ matrix.pyproject }}
          build_system: ${{ matrix.build_system }}
          install_maturin_zig: ${{ matrix.os == 'ubuntu-24.04-arm' }}
          rust_toolchain: ${{ needs.release-plan.outputs.rust_toolchain }}
          workspace_toml: ${{ needs.release-plan.outputs.workspace_toml }}
      - name: Build wheels (maturin)
        if: ${{ matrix.build_system == 'maturin' && matrix.os != 'ubuntu-24.04-arm' }}
        run: maturin build --release --manifest-path ${{ matrix.cargo_manifest }} --out dist
      - name: Build ARM64 Linux wheel (maturin + Zig)
        if: ${{ matrix.build_system == 'maturin' && matrix.os == 'ubuntu-24.04-arm' }}
        run: >-
          maturin build --release --manifest-path ${{ matrix.cargo_manifest }} --out dist
          --compatibility manylinux2014 --zig
      - name: Build wheels (setuptools)
        if: ${{ matrix.build_system == 'setuptools' }}
        run: |
          python -m pip install build==1.3.0
          python -m build --wheel --outdir dist '${{ matrix.source }}'
      - uses: actions/upload-artifact@v4
        with:
          name: python-wheel-${{ matrix.artifact }}-${{ matrix.os }}
          path: dist/*.whl

  build-python-sdists:
    if: ${{ needs.release-plan.outputs.has_python_sdists == 'true' }}
    needs: [gate-and-tag, release-plan]
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.release-plan.outputs.python_sdist_matrix) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}
      - uses: ./.github/actions/setup-python-release-build
        with:
          release_ref: ${{ needs.gate-and-tag.outputs.build_ref }}
          release_version: ${{ needs.gate-and-tag.outputs.release_version }}
          pyproject: ${{ matrix.pyproject }}
          build_system: ${{ matrix.build_system }}
          rust_toolchain: ${{ needs.release-plan.outputs.rust_toolchain }}
          workspace_toml: ${{ needs.release-plan.outputs.workspace_toml }}
      - name: Build sdist (maturin)
        if: ${{ matrix.build_system == 'maturin' }}
        run: maturin sdist --manifest-path ${{ matrix.cargo_manifest }} --out dist
      - name: Build sdist (setuptools)
        if: ${{ matrix.build_system == 'setuptools' }}
        run: |
          python -m pip install build==1.3.0
          python -m build --sdist --outdir dist '${{ matrix.source }}'
      - uses: actions/upload-artifact@v4
        with:
          name: python-sdist-${{ matrix.artifact }}
          path: dist/*.tar.gz

  publish-testpypi:
    # TestPyPI remains part of the non-production rehearsal. Production PyPI
    # publication is deliberately handled by pypi-publish.yml after the
    # immutable GitHub Release exists. Wheel/sdist jobs may be skipped when
    # the manifest declares no matching Python distributions.
    if: >-
      ${{ !failure() && !cancelled() &&
          needs.gate-and-tag.outputs.release_target == 'testpypi' &&
          (needs.build-python-wheels.result == 'success' || needs.build-python-sdists.result == 'success') }}
    needs: [gate-and-tag, release-plan, build-python-wheels, build-python-sdists]
    runs-on: ubuntu-latest
    environment: testpypi
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}
      - uses: actions/download-artifact@v4
        with:
          pattern: 'python-wheel-*'
          merge-multiple: true
          path: dist
      - uses: actions/download-artifact@v4
        with:
          pattern: 'python-sdist-*'
          merge-multiple: true
          path: dist
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install maturin
        if: ${{ needs.release-plan.outputs.python_upload_tool == 'maturin' }}
        run: python -m pip install maturin==1.9.4
      - name: Install twine
        if: ${{ needs.release-plan.outputs.python_upload_tool == 'twine' }}
        run: python -m pip install twine==6.1.0
      - name: Verify manifest-declared Python release assets
        shell: bash
        run: |
          set -euo pipefail
          python3 .github/scripts/release_artifacts.py verify-python-release-assets \
            --manifest "${RELEASE_ARTIFACT_MANIFEST}" \
            --asset-dir dist
      - name: Publish wheels and sdist to TestPyPI
        if: ${{ needs.release-plan.outputs.python_upload_tool == 'maturin' }}
        env:
          MATURIN_PYPI_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
          MATURIN_NON_INTERACTIVE: "1"
        run: maturin upload --repository testpypi --non-interactive --skip-existing dist/*.whl dist/*.tar.gz
      - name: Publish wheels and sdist to TestPyPI with twine
        if: ${{ needs.release-plan.outputs.python_upload_tool == 'twine' }}
        env:
          TWINE_NON_INTERACTIVE: "1"
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
        run: python -m twine upload --repository testpypi --skip-existing dist/*.whl dist/*.tar.gz

  release:
    # Runs whenever every needed job succeeded or was legitimately skipped
    # (crates or Python legs may be absent for this consumer). The GitHub
    # Release leg deliberately does not depend on crates.io publication: a
    # failed crates leg is retried in isolation via crates-publish.yml while
    # the release and its dependent post-release channels proceed.
    if: >-
      ${{ !failure() && !cancelled() &&
          needs.gate-and-tag.outputs.release_target == 'production' &&
          needs.build.result == 'success' }}
    needs: [gate-and-tag, build, build-python-wheels, build-python-sdists]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.gate-and-tag.outputs.build_ref }}

      - id: expected_assets
        name: Read expected release asset patterns from manifest
        shell: bash
        run: |
          set -euo pipefail
          {
            echo 'patterns<<EOF'
            python3 .github/scripts/release_artifacts.py release-asset-patterns --manifest "${RELEASE_ARTIFACT_MANIFEST}"
            echo '^checksums\.txt$'
            echo 'EOF'
          } >> "$GITHUB_OUTPUT"

      # Detect-and-skip: rebuilt archives are not reproducible, so re-uploading
      # over an existing complete release would silently change asset SHA256s
      # that Homebrew/Scoop may already pin. Replacing assets requires the
      # explicit replace_release_assets opt-in. The probe fails closed: only a
      # confirmed-absent (or confirmed-incomplete) release proceeds to
      # build/upload; an indeterminate probe result fails this job instead of
      # silently rebuilding over already-digested assets.
      - id: published_release_probe
        name: Probe for an already-complete published release (fail closed)
        uses: ./.github/actions/verify-published-release
        with:
          release_tag: ${{ needs.gate-and-tag.outputs.release_tag }}
          asset_patterns: ${{ steps.expected_assets.outputs.patterns }}
          probe: 'true'

      - name: Skip upload for the already-complete release
        if: ${{ steps.published_release_probe.outputs.release_state == 'complete' && inputs.replace_release_assets != true }}
        run: echo "GitHub Release ${{ needs.gate-and-tag.outputs.release_tag }} already exists with every expected asset; skipping upload. Dispatch with replace_release_assets=true to deliberately replace assets."

      - name: Log explicit asset replacement opt-in
        if: ${{ steps.published_release_probe.outputs.release_state == 'complete' && inputs.replace_release_assets == true }}
        run: echo "replace_release_assets=true; deliberately replacing assets on published release ${{ needs.gate-and-tag.outputs.release_tag }} (their SHA256s will change)."

      - name: Download all artifacts
        if: ${{ steps.published_release_probe.outputs.release_state != 'complete' || inputs.replace_release_assets == true }}
        uses: actions/download-artifact@v4
        with:
          path: artifacts

      - name: Collect archives
        if: ${{ steps.published_release_probe.outputs.release_state != 'complete' || inputs.replace_release_assets == true }}
        run: |
          mkdir -p release
          find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' \) -exec mv {} release/ \;
          find artifacts -type f -name '*.whl' -exec mv {} release/ \;
          ls -la release/

      - name: Generate checksums
        if: ${{ steps.published_release_probe.outputs.release_state != 'complete' || inputs.replace_release_assets == true }}
        working-directory: release
        run: |
          files=()
          for pattern in *.tar.gz *.zip *.whl; do
            for file in $pattern; do
              [[ -e "$file" ]] || continue
              files+=("$file")
            done
          done
          sha256sum "${files[@]}" > checksums.txt

      - name: Create GitHub Release
        if: ${{ steps.published_release_probe.outputs.release_state != 'complete' || inputs.replace_release_assets == true }}
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ needs.gate-and-tag.outputs.release_tag }}
          generate_release_notes: true
          files: |
            release/*