release.yml

name: RegistryStack Release
run-name: Publish RegistryStack ${{ inputs.tag }} (${{ inputs.request_id }})

on:
  workflow_dispatch:
    inputs:
      tag:
        description: Exact annotated release tag to publish
        required: true
        type: string
      request_id:
        description: Optional correlation ID generated by registry-release publish
        required: false
        type: string

permissions:
  contents: read

concurrency:
  group: registry-stack-release-${{ inputs.tag }}
  cancel-in-progress: false

env:
  REGISTRY: ghcr.io
  IMAGE_NAMESPACE: registrystack
  CRANE_VERSION: v0.21.2
  CRANE_LINUX_AMD64_SHA256: 897e7c342db072ba76531246fc18fbf3e8e298688b6ecf98916770984b263866
  COSIGN_VERSION: v3.0.4
  COSIGN_LINUX_AMD64_SHA256: 10dab2fd2170b5aa0d5c0673a9a2793304960220b314f6a873bf39c2f08287aa

jobs:
  verify:
    name: Verify tag and exact private candidate
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      actions: read
      attestations: read
      contents: read
      packages: read
    outputs:
      tag: ${{ steps.identity.outputs.tag }}
      version: ${{ steps.identity.outputs.version }}
      unit: ${{ steps.identity.outputs.unit }}
      asset_prefix: ${{ steps.identity.outputs.asset_prefix }}
      bundle_name: ${{ steps.identity.outputs.bundle_name }}
      release_id: ${{ steps.candidate.outputs.release_id }}
      source_sha: ${{ steps.identity.outputs.source_sha }}
      promotion_revision: ${{ steps.identity.outputs.promotion_revision }}
      workflow_revision: ${{ steps.candidate.outputs.workflow_revision }}
      docs_sha256: ${{ steps.candidate.outputs.docs_sha256 }}
      identifier_catalog_sha256: ${{ steps.candidate.outputs.identifier_catalog_sha256 }}
      client_registries: ${{ steps.candidate.outputs.client_registries }}
      client_registry_matrix: ${{ steps.candidate.outputs.client_registry_matrix }}
      client_registry_pypi_matrix: ${{ steps.candidate.outputs.client_registry_pypi_matrix }}
      candidate_run: ${{ steps.binding.outputs.run_id }}
      candidate_attempt: ${{ steps.binding.outputs.run_attempt }}
      manifest_sha256: ${{ steps.binding.outputs.manifest_sha256 }}
      destination_state: ${{ steps.release_destination.outputs.state }}
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.sha }}
          fetch-depth: 0
          persist-credentials: false
          submodules: false

      - name: Resolve exact tag identity
        id: identity
        env:
          RELEASE_TAG: ${{ inputs.tag }}
          REQUEST_ID: ${{ inputs.request_id }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ "${GITHUB_EVENT_NAME}" != workflow_dispatch ||
                "${GITHUB_REF}" != refs/heads/main ]]; then
            echo "Release publication must be dispatched from protected main" >&2
            exit 1
          fi
          if [[ -n "${REQUEST_ID}" && ! "${REQUEST_ID}" =~ ^[0-9a-f]{32}$ ]]; then
            echo "request_id must be empty or 32 lowercase hexadecimal characters" >&2
            exit 1
          fi
          tag="${RELEASE_TAG}"
          unit=stack
          asset_tag="${tag}"
          prefix=registry-stack
          if [[ "${tag}" == discovery/* ]]; then
            unit=discovery
            asset_tag="${tag#discovery/}"
            prefix=registry-discovery
          fi
          if [[ ! "${asset_tag}" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
            echo "Release tag must be canonical vMAJOR.MINOR.PATCH" >&2
            exit 1
          fi
          if [[ "${unit}" == stack && "${asset_tag%%.*}" != v0 ]]; then
            echo "Beta publication accepts only v0.x.y release tags" >&2
            exit 1
          fi
          version="${asset_tag#v}"
          IFS=. read -r version_major version_minor _ <<< "${version}"
          if [[ "${unit}" == stack ]] && (( version_major == 0 && version_minor < 19 )); then
            echo "pre-v0.19 releases are immutable historical evidence; use the corresponding ${tag} Git tag and archived assets" >&2
            exit 1
          fi
          git fetch --force origin \
            refs/heads/main:refs/remotes/origin/main \
            "refs/tags/${tag}:refs/tags/${tag}"
          if [[ "$(git cat-file -t "refs/tags/${tag}")" != tag ]]; then
            echo "Release tag must be annotated" >&2
            exit 1
          fi
          source_sha="$(git rev-parse --verify "refs/tags/${tag}^{}")"
          promotion_revision="$(git rev-parse HEAD)"
          git merge-base --is-ancestor \
            "${source_sha}" refs/remotes/origin/main
          git merge-base --is-ancestor \
            "${promotion_revision}" refs/remotes/origin/main
          {
            echo "tag=${tag}"
            echo "version=${version}"
            echo "unit=${unit}"
            echo "asset_prefix=${prefix}-${asset_tag}"
            echo "bundle_name=${prefix}-${asset_tag}-candidate.tar.gz"
            echo "source_sha=${source_sha}"
            echo "promotion_revision=${promotion_revision}"
          } >> "${GITHUB_OUTPUT}"

      - name: Parse compact candidate binding
        id: binding
        shell: bash
        run: |
          set -euo pipefail
          git for-each-ref --format='%(contents)' \
            "refs/tags/${{ steps.identity.outputs.tag }}" \
            > "${RUNNER_TEMP}/tag-message"
          PYTHONPATH=release/scripts python3 - \
            "${RUNNER_TEMP}/tag-message" "${GITHUB_OUTPUT}" <<'PY'
          import sys
          from pathlib import Path
          from release_candidate import parse_tag_binding

          message = Path(sys.argv[1]).read_text(encoding="utf-8")
          binding = parse_tag_binding(message.rstrip("\n"))
          with Path(sys.argv[2]).open("a", encoding="utf-8") as handle:
              for field in ("run_id", "run_attempt", "manifest_sha256"):
                  handle.write(f"{field}={binding[field]}\n")
          PY

      - name: Download exact candidate attempt
        env:
          GH_TOKEN: ${{ github.token }}
          RUN_ID: ${{ steps.binding.outputs.run_id }}
          RUN_ATTEMPT: ${{ steps.binding.outputs.run_attempt }}
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p promotion
          gh api "/repos/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}" \
            > promotion/trusted-run.json
          jq -e \
            --argjson run_id "${RUN_ID}" \
            --argjson run_attempt "${RUN_ATTEMPT}" \
            '.id == $run_id and
             .run_attempt == $run_attempt and
             .event == "repository_dispatch" and
             .path == ".github/workflows/release-candidate.yml" and
             .conclusion == "success"' promotion/trusted-run.json >/dev/null
          artifact_name="registry-stack-release-candidate-${RUN_ID}-${RUN_ATTEMPT}"
          gh api \
            "/repos/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}/artifacts?per_page=100" \
            | jq --arg name "${artifact_name}" \
            '[.artifacts[] | select(
              .name == $name and
              .expired == false and
              .workflow_run.id != null
            )] | select(length == 1) | .[0]' \
            > promotion/artifact.json
          artifact_id="$(jq -er .id promotion/artifact.json)"
          expected_archive_digest="$(jq -er '.digest | select(test("^sha256:[0-9a-f]{64}$"))' promotion/artifact.json)"
          gh api \
            "/repos/${GITHUB_REPOSITORY}/actions/artifacts/${artifact_id}/zip" \
            > promotion/candidate.zip
          test "sha256:$(sha256sum promotion/candidate.zip | awk '{print $1}')" = \
            "${expected_archive_digest}"
          unzip -q promotion/candidate.zip -d promotion/candidate
          expected="$(
            printf '%s\n' \
              release-candidate-manifest.json \
              "${{ steps.identity.outputs.asset_prefix }}-candidate.tar.gz" \
              | sort
          )"
          actual="$(
            find promotion/candidate -maxdepth 1 -type f -printf '%f\n' | sort
          )"
          test "${actual}" = "${expected}"
          cp promotion/trusted-run.json promotion/candidate/trusted-run.json

      - name: Verify binding, candidate, and attestations
        id: candidate
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/candidate/release-candidate-manifest.json
          bundle="promotion/candidate/${{ steps.identity.outputs.asset_prefix }}-candidate.tar.gz"
          test "$(sha256sum "${manifest}" | awk '{print $1}')" = \
            "${{ steps.binding.outputs.manifest_sha256 }}"
          mkdir -p promotion/extracted
          tar -xzf "${bundle}" -C promotion/extracted
          release_id="$(jq -er .release.release_id "${manifest}")"
          workflow_revision="$(jq -er .workflow.revision "${manifest}")"
          python3 release/scripts/release_candidate.py verify-tag-binding \
            --unit "${{ steps.identity.outputs.unit }}" \
            --message "${RUNNER_TEMP}/tag-message" \
            --manifest "${manifest}" \
            --bundle "${bundle}" \
            --bundle-root promotion/extracted \
            --trusted-run-metadata promotion/trusted-run.json \
            --tag-target "${{ steps.identity.outputs.source_sha }}" \
            --workflow-revision "${workflow_revision}" \
            --version "${{ steps.identity.outputs.version }}" \
            --release-id "${release_id}"
          test "$(jq -r .release.tag "${manifest}")" = "${{ steps.identity.outputs.tag }}"
          test "$(jq -r '.release.unit // "stack"' "${manifest}")" = "${{ steps.identity.outputs.unit }}"
          test "${workflow_revision}" = "${{ steps.identity.outputs.source_sha }}"
          python3 release/scripts/release_candidate.py verify-candidate \
            --unit "${{ steps.identity.outputs.unit }}" \
            --manifest "${manifest}" \
            --bundle "${bundle}" \
            --bundle-root promotion/extracted \
            --source-sha "${workflow_revision}" \
            --workflow-revision "${workflow_revision}" \
            --version "${{ steps.identity.outputs.version }}" \
            --release-id "${release_id}" \
            --run-id "${{ steps.binding.outputs.run_id }}" \
            --run-attempt "${{ steps.binding.outputs.run_attempt }}" \
            --promotion \
            --trusted-run-metadata promotion/trusted-run.json
          for subject in "${manifest}" "${bundle}"; do
            gh attestation verify "${subject}" \
              --repo "${GITHUB_REPOSITORY}" \
              --signer-workflow \
                "${GITHUB_REPOSITORY}/.github/workflows/release-candidate.yml" \
              --signer-digest "${workflow_revision}" \
              --source-ref refs/heads/main \
              --source-digest "${workflow_revision}" \
              --deny-self-hosted-runners
          done
          docs_sha256=
          identifier_catalog_sha256=
          if [[ "${{ steps.identity.outputs.unit }}" == stack ]]; then
          identifier_catalog_sha256="$(
            git show \
              "${{ steps.identity.outputs.source_sha }}:products/identifiers/generated/catalog.v1.json" \
              | sha256sum | awk '{print $1}'
          )"
          IFS=. read -r major minor patch <<<"${{ steps.identity.outputs.version }}"
          if ((
            major > 0 ||
            (major == 0 && (minor > 19 || (minor == 19 && patch >= 1)))
          )); then
            docs_sha256="$(
              jq -er '.docs.sha256 | select(test("^[0-9a-f]{64}$"))' \
                "${manifest}"
            )"
          fi
          client_registries="$(
            PYTHONPATH=release/scripts python3 - \
              "${{ steps.identity.outputs.version }}" <<'PY'
          import sys
          from release_candidate import CLIENT_REGISTRY_PACKAGE_MINIMUM_VERSION

          version = tuple(int(part) for part in sys.argv[1].split("."))
          print("true" if version >= CLIENT_REGISTRY_PACKAGE_MINIMUM_VERSION else "false")
          PY
          )"
          client_registry_matrix="$(
            PYTHONPATH=release/scripts python3 - \
              "${{ steps.identity.outputs.version }}" <<'PY'
          import json
          import sys
          from release_candidate import (
              DISCOVERY_CLIENT_PACKAGE_MINIMUM_VERSION,
              UNIFIED_CLIENT_PACKAGE_MINIMUM_VERSION,
          )

          version = tuple(int(part) for part in sys.argv[1].split("."))
          if version >= UNIFIED_CLIENT_PACKAGE_MINIMUM_VERSION:
              clients = ["stack"]
          else:
              # Standalone Relay packages exist only in the immutable
              # pre-unified release range. Current and future releases take
              # the stack branch above and cannot select Relay.
              clients = ["evidence", "relay"]
              if version >= DISCOVERY_CLIENT_PACKAGE_MINIMUM_VERSION:
                  clients.insert(0, "discovery")
          print(json.dumps({"client": clients}, separators=(",", ":")))
          PY
          )"
          client_registry_pypi_matrix="$(
            PYTHONPATH=release/scripts python3 - \
              "${{ steps.identity.outputs.version }}" <<'PY'
          import json
          import sys
          from release_candidate import (
              DISCOVERY_CLIENT_PACKAGE_MINIMUM_VERSION,
              UNIFIED_CLIENT_PACKAGE_MINIMUM_VERSION,
          )

          version = tuple(int(part) for part in sys.argv[1].split("."))
          if version >= UNIFIED_CLIENT_PACKAGE_MINIMUM_VERSION:
              clients = [{"client": "stack", "environment": "pypi"}]
          else:
              clients = [
                  {"client": "evidence", "environment": "pypi-evidence"},
                  {"client": "relay", "environment": "pypi"},
              ]
              if version >= DISCOVERY_CLIENT_PACKAGE_MINIMUM_VERSION:
                  clients.insert(0, {"client": "discovery", "environment": "pypi"})
          print(json.dumps({"include": clients}, separators=(",", ":")))
          PY
          )"
          else
            client_registries=false
            client_registry_matrix='{"client":["stack"]}'
            client_registry_pypi_matrix='{"include":[{"client":"stack","environment":"pypi"}]}'
          fi
          {
            echo "release_id=${release_id}"
            echo "workflow_revision=${workflow_revision}"
            echo "docs_sha256=${docs_sha256}"
            echo "identifier_catalog_sha256=${identifier_catalog_sha256}"
            echo "client_registries=${client_registries}"
            echo "client_registry_matrix=${client_registry_matrix}"
            echo "client_registry_pypi_matrix=${client_registry_pypi_matrix}"
          } >> "${GITHUB_OUTPUT}"

      - name: Classify absent, draft, or exact published release destination
        id: release_destination
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ steps.identity.outputs.tag }}"
          if release_id="$(
            gh release view "${tag}" \
              --repo "${GITHUB_REPOSITORY}" \
              --json databaseId \
              --jq .databaseId 2>/dev/null
          )"; then
            gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
              > promotion/existing-release.json
            jq -e \
              --argjson release_id "${release_id}" \
              --arg tag "${tag}" \
              --arg title "RegistryStack ${tag}" \
              --arg marker \
                "registry-stack-release-candidate-v2 manifest_sha256:${{ steps.binding.outputs.manifest_sha256 }}" \
              '.id == $release_id and
               .prerelease == false and
               .tag_name == $tag and
               .name == $title and
               ((.body // "") | contains($marker)) and
               ((.draft == true and .published_at == null) or
                (.draft == false and
                 (.published_at | type == "string" and length > 0)))' \
              promotion/existing-release.json >/dev/null
            state="$(jq -r 'if .draft then "draft" else "published" end' \
              promotion/existing-release.json)"
          else
            state=absent
          fi
          echo "state=${state}" >> "${GITHUB_OUTPUT}"

      - name: Upload verified promotion input
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion/candidate
          if-no-files-found: error
          overwrite: true
          retention-days: 2

  stage-draft:
    name: Create or reconcile the bound draft
    if: needs.verify.outputs.destination_state != 'published'
    needs: verify
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      actions: read
      contents: write
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Checkout exact tagged product source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.source_sha }}
          path: product-source
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Download verified promotion input
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Reverify and stage exact candidate payloads
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          bundle="promotion/${{ needs.verify.outputs.asset_prefix }}-candidate.tar.gz"
          test "$(sha256sum "${manifest}" | awk '{print $1}')" = \
            "${{ needs.verify.outputs.manifest_sha256 }}"
          mkdir -p extracted release-assets contract
          tar -xzf "${bundle}" -C extracted
          python3 release/scripts/release_candidate.py verify-candidate \
            --manifest "${manifest}" \
            --bundle "${bundle}" \
            --bundle-root extracted \
            --source-sha "${{ needs.verify.outputs.workflow_revision }}" \
            --workflow-revision "${{ needs.verify.outputs.workflow_revision }}" \
            --version "${{ needs.verify.outputs.version }}" \
            --release-id "${{ needs.verify.outputs.release_id }}" \
            --run-id "${{ needs.verify.outputs.candidate_run }}" \
            --run-attempt "${{ needs.verify.outputs.candidate_attempt }}" \
            --promotion \
            --trusted-run-metadata promotion/trusted-run.json
          while IFS= read -r name; do
            cp "extracted/${name}" "release-assets/${name}"
          done < <(jq -r '.payloads[].name' "${manifest}")
          public_manifest="${{ needs.verify.outputs.asset_prefix }}-release-manifest.json"
          cp "${manifest}" "release-assets/${public_manifest}"

      - name: Reconcile bound draft and upload exact staged inventory
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          while IFS= read -r -d '' file; do
            jq -n \
              --arg name "$(basename "${file}")" \
              --arg sha256 "$(sha256sum "${file}" | awk '{print $1}')" \
              --argjson size "$(stat -c %s "${file}")" \
              '{name:$name,sha256:$sha256,size:$size}'
          done < <(find release-assets -maxdepth 1 -type f -print0 | sort -z) \
            | jq -s 'sort_by(.name)' > contract/staged-assets.json
          release_view_error="${RUNNER_TEMP}/release-view.error"
          if release_id="$(
            gh release view "${tag}" \
              --repo "${GITHUB_REPOSITORY}" \
              --json databaseId \
              --jq .databaseId 2>"${release_view_error}"
          )"; then
            gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
              > "${RUNNER_TEMP}/existing-draft.json"
            jq -e \
              --argjson release_id "${release_id}" \
              --arg tag "${tag}" \
              --arg title "RegistryStack ${tag}" \
              --arg marker \
                "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
              'select(
                .id == $release_id and
                .draft == true and
                .prerelease == false and
                .tag_name == $tag and
                .name == $title and
                ((.body // "") | contains($marker))
              ) | .id' \
              "${RUNNER_TEMP}/existing-draft.json" >/dev/null
          elif grep -Fxq 'release not found' "${release_view_error}"; then
            cp "product-source/release/notes/${tag}.md" contract/draft-notes.md
            printf \
              '\n<!-- registry-stack-release-candidate-v2 manifest_sha256:%s -->\n' \
              "${{ needs.verify.outputs.manifest_sha256 }}" \
              >> contract/draft-notes.md
            latest_args=()
            if [[ "${{ needs.verify.outputs.unit }}" != stack ]]; then latest_args+=(--latest=false); fi
            gh release create "${tag}" "${latest_args[@]}" \
              --verify-tag \
              --draft \
              --title "RegistryStack ${tag}" \
              --notes-file contract/draft-notes.md
          else
            cat "${release_view_error}" >&2
            exit 1
          fi
          release_id="$(
            gh release view "${tag}" \
              --repo "${GITHUB_REPOSITORY}" \
              --json databaseId \
              --jq .databaseId
          )"
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > "${RUNNER_TEMP}/staged-draft.json"
          jq -e \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            --argjson release_id "${release_id}" \
            '.id == $release_id and
             .draft == true and
             .prerelease == false and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            "${RUNNER_TEMP}/staged-draft.json" >/dev/null
          {
            printf '%s\n' \
              SHA256SUMS \
              "${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.sigstore.json" \
              "${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.intoto.jsonl"
          } | sort -u > contract/retryable-final-assets
          jq -r '.[].name' contract/staged-assets.json \
            | sort -u > contract/expected-staged-assets
          {
            cat contract/expected-staged-assets
            cat contract/retryable-final-assets
          } | sort -u > contract/allowed-staged-assets
          jq -r '.assets[].name' "${RUNNER_TEMP}/staged-draft.json" \
            | sort -u > contract/actual-staged-assets
          if ! comm -13 \
              contract/allowed-staged-assets \
              contract/actual-staged-assets \
              > contract/unexpected-staged-assets; then
            exit 1
          fi
          if [[ -s contract/unexpected-staged-assets ]]; then
            echo "Draft contains assets outside the deterministic staged roster" >&2
            cat contract/unexpected-staged-assets >&2
            exit 1
          fi
          additions=()
          while IFS=$'\t' read -r name sha256 size; do
            matches="$(
              jq -c --arg name "${name}" \
                '[.assets[] | select(.name == $name)]' \
                "${RUNNER_TEMP}/staged-draft.json"
            )"
            count="$(jq -r length <<<"${matches}")"
            if [[ "${count}" == 0 ]]; then
              additions+=("release-assets/${name}")
            elif [[ "${count}" == 1 ]]; then
              jq -e \
                --arg digest "sha256:${sha256}" \
                --argjson size "${size}" \
                '.[0].digest == $digest and .[0].size == $size' \
                <<<"${matches}" >/dev/null
            else
              echo "Draft repeats staged asset ${name}" >&2
              exit 1
            fi
          done < <(
            jq -r '.[] | [.name,.sha256,.size] | @tsv' \
              contract/staged-assets.json
          )
          if ((${#additions[@]} > 0)); then
            gh release upload "${tag}" "${additions[@]}" \
              --repo "${GITHUB_REPOSITORY}"
          fi
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > "${RUNNER_TEMP}/staged-draft.json"
          while IFS=$'\t' read -r name sha256 size; do
            jq -e \
              --arg name "${name}" \
              --arg digest "sha256:${sha256}" \
              --argjson size "${size}" \
              '[.assets[]
                | select(
                    .name == $name and
                    .digest == $digest and
                    .size == $size
                  )]
               | length == 1' \
              "${RUNNER_TEMP}/staged-draft.json" >/dev/null
          done < <(
            jq -r '.[] | [.name,.sha256,.size] | @tsv' \
              contract/staged-assets.json
          )
          cp "${RUNNER_TEMP}/staged-draft.json" contract/draft-release.json

      - name: Upload draft reconciliation contract
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: release-draft-contract-${{ github.run_id }}
          path: contract
          if-no-files-found: error
          overwrite: true
          retention-days: 2

  promote-images:
    name: Reconcile staged draft, then promote exact image manifests
    needs:
      - verify
      - stage-draft
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      actions: read
      contents: write
      packages: write
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Download verified candidate and draft contract
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Download exact draft contract
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-draft-contract-${{ github.run_id }}
          path: contract

      - name: Install pinned image inspector
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
            -o "${RUNNER_TEMP}/crane.tar.gz"
          echo "${CRANE_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/crane.tar.gz" \
            | sha256sum --check --strict
          tar -xzf "${RUNNER_TEMP}/crane.tar.gz" \
            -C "${HOME}/.local/bin" crane
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Reconcile exact staged draft before first public image write
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          release_id="$(jq -er '.id | select(type == "number" and . > 0)' \
            contract/draft-release.json)"
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > contract/current-draft-release.json
          mv contract/current-draft-release.json contract/draft-release.json
          jq -e \
            --argjson release_id "${release_id}" \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            '.id == $release_id and
             .draft == true and
             .prerelease == false and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            contract/draft-release.json >/dev/null
          jq -r '.[].name' contract/staged-assets.json \
            | sort > contract/expected-assets
          jq -r '.assets[].name' contract/draft-release.json \
            | sort > contract/observed-assets
          comm -23 \
            contract/observed-assets \
            contract/retryable-final-assets \
            > contract/actual-assets
          diff -u contract/expected-assets contract/actual-assets
          mkdir -p draft
          gh release download "${tag}" \
            --repo "${GITHUB_REPOSITORY}" --dir draft
          while IFS=$'\t' read -r name sha256 size; do
            test "$(stat -c %s "draft/${name}")" = "${size}"
            test "$(sha256sum "draft/${name}" | awk '{print $1}')" = "${sha256}"
            test "$(jq -er --arg name "${name}" \
              '.assets[] | select(.name == $name) | .digest' \
              contract/draft-release.json)" = "sha256:${sha256}"
          done < <(
            jq -r '.[] | [.name,.sha256,.size] | @tsv' \
              contract/staged-assets.json
          )

      - name: Recheck candidate expiry immediately before registry login
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          expires_at="$(jq -er '.validity.expires_at' "${manifest}")"
          expires_epoch="$(date -u -d "${expires_at}" +%s)"
          now_epoch="$(date -u +%s)"
          if (( now_epoch >= expires_epoch )); then
            echo "Candidate expired before public image promotion" >&2
            exit 1
          fi

      - name: Log in for exact candidate promotion
        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Reconcile exact image digests
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          while IFS=$'\t' read -r candidate_ref digest final_ref; do
            test "$(crane digest "${candidate_ref}")" = "${digest}"
            destination="$(
              python3 release/scripts/release_workflow_guard.py \
                public-image-destination \
                --final-ref "${final_ref}" \
                --namespace "${IMAGE_NAMESPACE}"
            )"
            IFS=$'\t' read -r package tag <<<"${destination}"
            package_metadata="${RUNNER_TEMP}/${package}-package.json"
            gh api "/orgs/${IMAGE_NAMESPACE}/packages/container/${package}" \
              > "${package_metadata}"
            python3 release/scripts/release_workflow_guard.py \
              require-package-visibility \
              --metadata "${package_metadata}" \
              --package "${package}" \
              --visibility public
            versions="${RUNNER_TEMP}/${package}-versions.json"
            gh api --paginate --slurp \
              "/orgs/${IMAGE_NAMESPACE}/packages/container/${package}/versions?per_page=100" \
              > "${versions}"
            state="$(
              python3 release/scripts/release_workflow_guard.py \
              reconcile-image-tag \
              --metadata "${versions}" \
              --tag "${tag}" \
              --expected-digest "${digest}"
            )"
            if [[ "${state}" == absent ]]; then
              crane copy "${candidate_ref}" "${final_ref}"
            else
              test "${state}" = present
            fi
            test "$(crane digest "${final_ref}")" = "${digest}"
          done < <(
            jq -r '.images[] |
              [.candidate_ref,.digest,.final_ref] | @tsv' "${manifest}"
          )

  finalize-assets:
    name: Finalize the signed Beta asset closure
    needs:
      - verify
      - stage-draft
      - promote-images
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      actions: read
      attestations: write
      contents: write
      id-token: write
      packages: read
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Download exact candidate and staged draft contract
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Download exact staged draft contract
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-draft-contract-${{ github.run_id }}
          path: contract

      - name: Install pinned image inspector
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
            -o "${RUNNER_TEMP}/crane.tar.gz"
          echo "${CRANE_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/crane.tar.gz" \
            | sha256sum --check --strict
          tar -xzf "${RUNNER_TEMP}/crane.tar.gz" \
            -C "${HOME}/.local/bin" crane
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Install pinned checksum signer
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64" \
            -o "${RUNNER_TEMP}/cosign"
          echo "${COSIGN_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/cosign" \
            | sha256sum --check --strict
          install -m 0755 "${RUNNER_TEMP}/cosign" "${HOME}/.local/bin/cosign"
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Clean retryable final additions and reverify exact staged assets
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          mkdir -p release-assets
          release_id="$(jq -er '.id | select(type == "number" and . > 0)' \
            contract/draft-release.json)"
          require_bound_draft() {
            gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
              > contract/current-draft-release.json
            mv contract/current-draft-release.json contract/draft-release.json
            jq -e \
              --arg tag "${tag}" \
              --arg title "RegistryStack ${tag}" \
              --arg marker \
                "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
              '.draft == true and
               .prerelease == false and
               .tag_name == $tag and
               .name == $title and
               ((.body // "") | contains($marker))' \
              contract/draft-release.json >/dev/null
          }
          require_bound_draft
          {
            jq -r '.[].name' contract/staged-assets.json
            cat contract/retryable-final-assets
          } | sort -u > contract/allowed-assets
          jq -r '.assets[].name' contract/draft-release.json \
            | sort -u > contract/actual-assets
          if ! comm -23 contract/actual-assets contract/allowed-assets \
              > contract/unexpected-assets; then
            exit 1
          fi
          if [[ -s contract/unexpected-assets ]]; then
            echo "Draft contains assets outside the staged and retryable rosters" >&2
            cat contract/unexpected-assets >&2
            exit 1
          fi
          # Sigstore bundles are intentionally nondeterministic. On a failed
          # finalizer retry, remove only the closed final-addition roster from
          # this exact candidate draft, then regenerate the closure together.
          while IFS= read -r name; do
            # Re-fetch the bound draft inside the loop so an early publication
            # cannot race a later destructive asset mutation.
            require_bound_draft
            asset_id="$(
              jq -er --arg name "${name}" \
                '.assets[] | select(.name == $name) | .id' \
                contract/draft-release.json 2>/dev/null || true
            )"
            if [[ -n "${asset_id}" ]]; then
              gh api --method DELETE \
                "repos/${GITHUB_REPOSITORY}/releases/assets/${asset_id}"
            fi
          done < contract/retryable-final-assets
          require_bound_draft
          jq -r '.[].name' contract/staged-assets.json \
            | sort > contract/expected-assets
          jq -r '.assets[].name' contract/draft-release.json \
            | sort > contract/actual-assets
          diff -u contract/expected-assets contract/actual-assets
          gh release download "${tag}" \
            --repo "${GITHUB_REPOSITORY}" --dir release-assets
          while IFS=$'\t' read -r name sha256 size; do
            test "$(stat -c %s "release-assets/${name}")" = "${size}"
            test "$(sha256sum "release-assets/${name}" | awk '{print $1}')" = "${sha256}"
            test "$(jq -er --arg name "${name}" \
              '.assets[] | select(.name == $name) | .digest' \
              contract/draft-release.json)" = "sha256:${sha256}"
          done < <(
            jq -r '.[] | [.name,.sha256,.size] | @tsv' \
              contract/staged-assets.json
          )

      - name: Sign the checksum closure
        shell: bash
        run: |
          set -euo pipefail
          (
            cd release-assets
            find . -maxdepth 1 -type f ! -name SHA256SUMS -print0 \
              | sort -z | xargs -0 sha256sum | sed 's#  \./#  #'
          ) > release-assets/SHA256SUMS
          checksum_bundle="release-assets/${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.sigstore.json"
          cosign sign-blob --yes \
            --bundle "${checksum_bundle}" \
            release-assets/SHA256SUMS
          test -s "${checksum_bundle}"

      # Attest the checksum inventory assembled by this publication workflow.
      # The verified candidate attestations retain the payload build binding.
      # The action emits a Sigstore bundle containing a DSSE envelope.
      - name: Attest the signed checksum closure
        id: provenance
        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
        with:
          subject-path: release-assets/SHA256SUMS
          show-summary: false

      - name: Upload the checksum closure and its provenance
        env:
          GH_TOKEN: ${{ github.token }}
          PROVENANCE_BUNDLE: ${{ steps.provenance.outputs.bundle-path }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          provenance_asset="release-assets/${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.intoto.jsonl"
          test -s "${PROVENANCE_BUNDLE}"
          jq -e '.dsseEnvelope.payloadType == "application/vnd.in-toto+json"' \
            "${PROVENANCE_BUNDLE}" >/dev/null
          cp "${PROVENANCE_BUNDLE}" "${provenance_asset}"
          mapfile -d '' -t staged < <(
            jq -r '.[].name' contract/staged-assets.json \
              | while IFS= read -r name; do
                  printf '%s\0' "release-assets/${name}"
                done
          )
          mapfile -d '' -t additions < <(
            find release-assets -maxdepth 1 -type f -print0 \
              | sort -z \
              | while IFS= read -r -d '' file; do
                  skip=0
                  for original in "${staged[@]}"; do
                    if [[ "${file}" == "${original}" ]]; then
                      skip=1
                      break
                    fi
                  done
                  if ((skip == 0)); then
                    printf '%s\0' "${file}"
                  fi
                done
          )
          release_id="$(jq -er '.id | select(type == "number" and . > 0)' \
            contract/draft-release.json)"
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > contract/final-upload-release.json
          jq -e \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            '.draft == true and
             .prerelease == false and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            contract/final-upload-release.json >/dev/null
          gh release upload "${tag}" "${additions[@]}" \
            --repo "${GITHUB_REPOSITORY}"
          while IFS= read -r -d '' file; do
            jq -n \
              --arg name "$(basename "${file}")" \
              --arg sha256 "$(sha256sum "${file}" | awk '{print $1}')" \
              --argjson size "$(stat -c %s "${file}")" \
              '{name:$name,sha256:$sha256,size:$size}'
          done < <(find release-assets -maxdepth 1 -type f -print0 | sort -z) \
            | jq -s 'sort_by(.name)' > contract/final-assets.json

      - name: Upload final reconciliation contract
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: release-final-contract-${{ github.run_id }}
          path: contract
          if-no-files-found: error
          overwrite: true
          retention-days: 2

  publish:
    name: Publish the reconciled Beta draft
    if: >-
      always() &&
      needs.verify.result == 'success' &&
      needs.stage-draft.result == 'success' &&
      needs.promote-images.result == 'success' &&
      needs.finalize-assets.result == 'success' &&
      (needs.verify.outputs.client_registries != 'true' ||
       (needs.publish_client_npm.result == 'success' &&
        needs.publish_client_pypi.result == 'success'))
    needs:
      - verify
      - stage-draft
      - promote-images
      - finalize-assets
      - publish_client_npm
      - publish_client_pypi
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      actions: read
      attestations: read
      contents: write
    steps:
      - name: Download exact candidate manifest
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Download exact final contract
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-final-contract-${{ github.run_id }}
          path: contract

      - name: Classify exact bound draft or published release
        id: release_state
        env:
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          # Only this failed-job retry may observe the prior PATCH. A new
          # workflow run still rejects every pre-existing public release.
          release_id="$(jq -er '.id | select(type == "number" and . > 0)' \
            contract/draft-release.json)"
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > classified-release.json
          classification="$(
            jq -er \
              --arg tag "${tag}" \
              --arg title "RegistryStack ${tag}" \
              --arg marker \
                "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
              'select(
                 .prerelease == false and
                 .tag_name == $tag and
                 .name == $title and
                 ((.body // "") | contains($marker)) and
                 (.id | type == "number")
               ) |
               if .draft == true and .published_at == null then
                 ["draft", (.id | tostring)] | @tsv
               elif .draft == false and
                    (.published_at | type == "string" and length > 0) then
                 ["published", (.id | tostring)] | @tsv
               else empty end' \
              classified-release.json
          )"
          IFS=$'\t' read -r release_state release_id <<<"${classification}"
          {
            echo "release_id=${release_id}"
            echo "release_state=${release_state}"
          } >> "${GITHUB_OUTPUT}"

      - name: Install pinned image verifier
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
            -o "${RUNNER_TEMP}/crane.tar.gz"
          echo "${CRANE_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/crane.tar.gz" \
            | sha256sum --check --strict
          tar -xzf "${RUNNER_TEMP}/crane.tar.gz" \
            -C "${HOME}/.local/bin" crane
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Install pinned cosign verifier
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64" \
            -o "${RUNNER_TEMP}/cosign"
          echo "${COSIGN_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/cosign" \
            | sha256sum --check --strict
          install -m 0755 "${RUNNER_TEMP}/cosign" "${HOME}/.local/bin/cosign"
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Recheck complete signed release and exact public images
        env:
          GH_TOKEN: ${{ github.token }}
          EXPECTED_RELEASE_ID: ${{ steps.release_state.outputs.release_id }}
          EXPECTED_RELEASE_STATE: ${{ steps.release_state.outputs.release_state }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          manifest=promotion/release-candidate-manifest.json
          gh api "repos/${GITHUB_REPOSITORY}/releases/${EXPECTED_RELEASE_ID}" \
            > release-state.json
          jq -e \
            --argjson release_id "${EXPECTED_RELEASE_ID}" \
            --arg release_state "${EXPECTED_RELEASE_STATE}" \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            '.id == $release_id and
             (($release_state == "draft" and
               .draft == true and
               .published_at == null) or
              ($release_state == "published" and
               .draft == false and
               (.published_at | type == "string" and length > 0))) and
             .prerelease == false and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            release-state.json >/dev/null
          jq -r '.[].name' contract/final-assets.json \
            | sort > expected-assets
          jq -r '.assets[].name' release-state.json | sort > actual-assets
          diff -u expected-assets actual-assets
          mkdir -p draft
          gh release download "${tag}" \
            --repo "${GITHUB_REPOSITORY}" --dir draft
          while IFS=$'\t' read -r name sha256 size; do
            test "$(stat -c %s "draft/${name}")" = "${size}"
            test "$(sha256sum "draft/${name}" | awk '{print $1}')" = "${sha256}"
            test "$(jq -er --arg name "${name}" \
              '.assets[] | select(.name == $name) | .digest' \
              release-state.json)" = "sha256:${sha256}"
          done < <(
            jq -r '.[] | [.name,.sha256,.size] | @tsv' \
              contract/final-assets.json
          )
          (
            cd draft
            sha256sum --check --strict SHA256SUMS
          )
          identity="https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/heads/main"
          cosign verify-blob draft/SHA256SUMS \
            --bundle \
              "draft/${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.sigstore.json" \
            --certificate-identity "${identity}" \
            --certificate-oidc-issuer \
              https://token.actions.githubusercontent.com
          gh attestation verify draft/SHA256SUMS \
            --bundle "draft/${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.intoto.jsonl" \
            --repo "${GITHUB_REPOSITORY}" \
            --signer-workflow \
              "${GITHUB_REPOSITORY}/.github/workflows/release.yml" \
            --source-ref refs/heads/main \
            --deny-self-hosted-runners
          while IFS=$'\t' read -r digest final_ref; do
            test "$(crane digest "${final_ref}")" = "${digest}"
          done < <(jq -r '.images[] | [.digest,.final_ref] | @tsv' "${manifest}")
          required=(
            SHA256SUMS
            "${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.sigstore.json"
            "${{ needs.verify.outputs.asset_prefix }}-SHA256SUMS.intoto.jsonl"
          )
          for name in "${required[@]}"; do
            jq -e --arg name "${name}" \
              '.assets[] | select(.name == $name)' \
              release-state.json >/dev/null
          done

      - name: Publish immutable release
        env:
          GH_TOKEN: ${{ github.token }}
          EXPECTED_RELEASE_ID: ${{ steps.release_state.outputs.release_id }}
          EXPECTED_RELEASE_STATE: ${{ steps.release_state.outputs.release_state }}
        shell: bash
        run: |
          set -euo pipefail
          tag="${{ needs.verify.outputs.tag }}"
          release_id="${EXPECTED_RELEASE_ID}"
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > publish-state.json
          jq -e \
            --argjson release_id "${release_id}" \
            --arg release_state "${EXPECTED_RELEASE_STATE}" \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            '.id == $release_id and
             (($release_state == "draft" and
               .draft == true and
               .published_at == null) or
              ($release_state == "published" and
               .draft == false and
               (.published_at | type == "string" and length > 0))) and
             .prerelease == false and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            publish-state.json >/dev/null
          if [[ "${EXPECTED_RELEASE_STATE}" == draft ]]; then
            latest_args=()
            if [[ "${{ needs.verify.outputs.unit }}" != stack ]]; then latest_args+=(-f make_latest=false); fi
            gh api --method PATCH \
              "repos/${GITHUB_REPOSITORY}/releases/${release_id}" "${latest_args[@]}" \
              -F draft=false \
              -F prerelease=false >/dev/null
          fi
          gh api "repos/${GITHUB_REPOSITORY}/releases/${release_id}" \
            > published-release.json
          jq -e \
            --argjson release_id "${release_id}" \
            --arg tag "${tag}" \
            --arg title "RegistryStack ${tag}" \
            --arg marker \
              "registry-stack-release-candidate-v2 manifest_sha256:${{ needs.verify.outputs.manifest_sha256 }}" \
            '.id == $release_id and
             .draft == false and
             .prerelease == false and
             (.published_at | type == "string" and length > 0) and
             .tag_name == $tag and
             .name == $title and
             ((.body // "") | contains($marker))' \
            published-release.json >/dev/null

  closeout-published:
    name: Verify an exact already-published release
    if: needs.verify.outputs.destination_state == 'published'
    needs: verify
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    permissions:
      contents: read
      packages: read
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Install pinned public-release verifiers
        shell: bash
        run: |
          set -euo pipefail
          mkdir -p "${HOME}/.local/bin"
          curl -sSfL \
            "https://github.com/google/go-containerregistry/releases/download/${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
            -o "${RUNNER_TEMP}/crane.tar.gz"
          echo "${CRANE_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/crane.tar.gz" \
            | sha256sum --check --strict
          tar -xzf "${RUNNER_TEMP}/crane.tar.gz" \
            -C "${HOME}/.local/bin" crane
          curl -sSfL \
            "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64" \
            -o "${RUNNER_TEMP}/cosign"
          echo "${COSIGN_LINUX_AMD64_SHA256}  ${RUNNER_TEMP}/cosign" \
            | sha256sum --check --strict
          install -m 0755 "${RUNNER_TEMP}/cosign" "${HOME}/.local/bin/cosign"
          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"

      - name: Verify the minimum immutable public contract
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          release/scripts/registry-release verify-public \
            --tag "${{ needs.verify.outputs.tag }}"

  publish_client_npm:
    name: Publish exact ${{ matrix.client }} client packages to npm
    if: >-
      needs.verify.outputs.client_registries == 'true' &&
      needs.verify.outputs.destination_state != 'published'
    needs:
      - verify
      - finalize-assets
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    environment: npm
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.verify.outputs.client_registry_matrix) }}
    permissions:
      actions: read
      contents: read
      id-token: write
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Download exact verified candidate
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Recheck candidate expiry after environment approval
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          expires_at="$(jq -er '.validity.expires_at' "${manifest}")"
          expires_epoch="$(date -u -d "${expires_at}" +%s)"
          now_epoch="$(date -u +%s)"
          if (( now_epoch >= expires_epoch )); then
            echo "Candidate expired before npm publication" >&2
            exit 1
          fi

      - name: Setup trusted npm publisher runtime
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.21.0
          registry-url: https://registry.npmjs.org
          package-manager-cache: false

      - name: Extract and validate the exact npm distribution
        shell: bash
        run: |
          set -euo pipefail
          node -e 'const [major, minor] = process.versions.node.split(".").map(Number); if (major < 22 || (major === 22 && minor < 14)) process.exit(1)'
          npm_version="$(npm --version)"
          python3 - "${npm_version}" <<'PY'
          import sys
          version = tuple(int(part) for part in sys.argv[1].split("."))
          if version < (11, 5, 1):
              raise SystemExit("trusted publishing requires npm >= 11.5.1")
          PY
          bundle="promotion/${{ needs.verify.outputs.asset_prefix }}-candidate.tar.gz"
          mkdir -p dist
          tar -xzf "${bundle}" -C dist
          python3 release/scripts/client_registry.py validate-dist \
            --directory dist \
            --version "${{ needs.verify.outputs.version }}" \
            --client "${{ matrix.client }}"

      - name: Reconcile platform packages, then publish the root package
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          expires_at="$(jq -er '.validity.expires_at' "${manifest}")"
          expires_epoch="$(date -u -d "${expires_at}" +%s)"
          require_unexpired_candidate() {
            if (( $(date -u +%s) >= expires_epoch )); then
              echo "Candidate expired before npm publication" >&2
              exit 1
            fi
          }
          version="${{ needs.verify.outputs.version }}"
          client="${{ matrix.client }}"
          if [[ "${client}" == stack ]]; then
            platform_packages=(
              "registrystack-client-darwin-arm64-${version}.tgz"
              "registrystack-client-linux-arm64-gnu-${version}.tgz"
              "registrystack-client-linux-x64-gnu-${version}.tgz"
            )
            root_package="registrystack-client-${version}.tgz"
          else
            platform_packages=(
              "registrystack-${client}-client-darwin-arm64-${version}.tgz"
              "registrystack-${client}-client-linux-arm64-gnu-${version}.tgz"
              "registrystack-${client}-client-linux-x64-gnu-${version}.tgz"
            )
            root_package="registrystack-${client}-client-${version}.tgz"
          fi
          absent_platforms=()
          for name in "${platform_packages[@]}"; do
            tarball="dist/${name}"
            state="$(python3 release/scripts/client_registry.py npm-state \
              --tarball "${tarball}")"
            if [[ "${state}" == absent ]]; then
              absent_platforms+=("${name}")
            else
              test "${state}" = present
            fi
          done
          for name in "${absent_platforms[@]}"; do
            tarball="dist/${name}"
            require_unexpired_candidate
            npm publish "./${tarball}" --access public --provenance
          done
          platform_deadline=$((SECONDS + 600))
          while true; do
            absent_platforms=()
            for name in "${platform_packages[@]}"; do
              tarball="dist/${name}"
              observed="$(python3 release/scripts/client_registry.py npm-state \
                --tarball "${tarball}")"
              if [[ "${observed}" == absent ]]; then
                absent_platforms+=("${name}")
              else
                test "${observed}" = present
              fi
            done
            if [[ "${#absent_platforms[@]}" -eq 0 ]]; then
              break
            fi
            if (( SECONDS >= platform_deadline )); then
              printf 'npm did not expose exact platform package %s\n' \
                "${absent_platforms[@]}" >&2
              exit 1
            fi
            sleep 10
          done
          root_tarball="dist/${root_package}"
          root_state="$(python3 release/scripts/client_registry.py npm-state \
            --tarball "${root_tarball}")"
          if [[ "${root_state}" == absent ]]; then
            require_unexpired_candidate
            npm publish "./${root_tarball}" --access public --provenance
          else
            test "${root_state}" = present
          fi
          root_deadline=$((SECONDS + 600))
          while true; do
            observed="$(python3 release/scripts/client_registry.py npm-state \
              --tarball "${root_tarball}")"
            if [[ "${observed}" == present ]]; then
              break
            fi
            test "${observed}" = absent
            if (( SECONDS >= root_deadline )); then
              echo "npm did not expose exact root package ${root_package}" >&2
              exit 1
            fi
            sleep 10
          done

  publish_client_pypi:
    name: Publish exact ${{ matrix.client }} client wheels to PyPI
    if: >-
      needs.verify.outputs.client_registries == 'true' &&
      needs.verify.outputs.destination_state != 'published'
    needs:
      - verify
      - finalize-assets
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    environment: ${{ matrix.environment }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.verify.outputs.client_registry_pypi_matrix) }}
    permissions:
      actions: read
      contents: read
      id-token: write
    steps:
      - name: Checkout protected promotion workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.verify.outputs.promotion_revision }}
          fetch-depth: 1
          persist-credentials: false
          submodules: false

      - name: Download exact verified candidate
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-promotion-input-${{ github.run_id }}
          path: promotion

      - name: Recheck candidate expiry after environment approval
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          expires_at="$(jq -er '.validity.expires_at' "${manifest}")"
          expires_epoch="$(date -u -d "${expires_at}" +%s)"
          now_epoch="$(date -u +%s)"
          if (( now_epoch >= expires_epoch )); then
            echo "Candidate expired before PyPI publication" >&2
            exit 1
          fi

      - name: Extract and classify the exact PyPI distribution
        id: pypi_state
        shell: bash
        run: |
          set -euo pipefail
          version="${{ needs.verify.outputs.version }}"
          client="${{ matrix.client }}"
          bundle="promotion/${{ needs.verify.outputs.asset_prefix }}-candidate.tar.gz"
          mkdir -p extracted dist
          tar -xzf "${bundle}" -C extracted
          for platform in manylinux_2_17_x86_64.manylinux2014_x86_64 manylinux_2_17_aarch64.manylinux2014_aarch64 macosx_11_0_arm64; do
            # The wheels keep the stable ABI tag of the release that built
            # them; pypi-state holds the exact names for this version.
            cp "extracted/registry_${client}_client-${version}-"cp3*-abi3-"${platform}.whl" dist/
          done
          state="$(python3 release/scripts/client_registry.py pypi-state \
            --directory dist --version "${version}" --client "${client}")"
          echo "state=${state}" >> "${GITHUB_OUTPUT}"

      - name: Recheck candidate expiry immediately before PyPI publication
        if: steps.pypi_state.outputs.state != 'present'
        shell: bash
        run: |
          set -euo pipefail
          manifest=promotion/release-candidate-manifest.json
          expires_at="$(jq -er '.validity.expires_at' "${manifest}")"
          expires_epoch="$(date -u -d "${expires_at}" +%s)"
          now_epoch="$(date -u +%s)"
          if (( now_epoch >= expires_epoch )); then
            echo "Candidate expired before PyPI publication" >&2
            exit 1
          fi

      - name: Publish absent exact wheels through PyPI trusted publishing
        if: steps.pypi_state.outputs.state != 'present'
        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
        with:
          packages-dir: dist
          skip-existing: true

      - name: Verify the complete immutable PyPI release
        shell: bash
        run: |
          set -euo pipefail
          deadline=$((SECONDS + 600))
          while true; do
            state="$(python3 release/scripts/client_registry.py pypi-state \
              --directory dist \
              --version "${{ needs.verify.outputs.version }}" \
              --client "${{ matrix.client }}")"
            if [[ "${state}" == present ]]; then
              exit 0
            fi
            if (( SECONDS >= deadline )); then
              echo "PyPI did not expose the complete exact wheel set" >&2
              exit 1
            fi
            sleep 10
          done

  dispatch-docs:
    name: Dispatch authenticated docs promotion
    if: >-
      always() &&
      needs.verify.outputs.docs_sha256 != '' &&
      (needs.publish.result == 'success' ||
       needs.closeout-published.result == 'success')
    needs:
      - verify
      - publish
      - closeout-published
    runs-on: ubuntu-24.04
    timeout-minutes: 2
    permissions:
      actions: write
    steps:
      - name: Dispatch authenticated docs promotion
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          gh workflow run docs-pages.yml \
            --repo "${GITHUB_REPOSITORY}" \
            --ref main \
            -f "released_tag=${{ needs.verify.outputs.tag }}" \
            -f "docs_sha256=${{ needs.verify.outputs.docs_sha256 }}" \
            -f "request_id=${{ inputs.request_id }}"

  publish-identifiers:
    name: Publish exact identifier catalog
    if: >-
      always() && needs.verify.outputs.unit == 'stack' &&
      (needs.publish.result == 'success' ||
       needs.closeout-published.result == 'success')
    needs:
      - verify
      - publish
      - closeout-published
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    steps:
      - name: Dispatch and verify exact identifier publication
        env:
          GH_TOKEN: ${{ secrets.IDENTIFIER_PUBLISHER_TOKEN }}
          RELEASE_REQUEST_ID: ${{ inputs.request_id }}
        shell: bash
        run: |
          set -euo pipefail
          request_id="${RELEASE_REQUEST_ID}"
          if [[ -z "${request_id}" ]]; then
            request_id="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
          fi
          # The dispatch response names the run it created. A rerun dispatches
          # under the same request ID, so a title search can find an earlier run.
          target_run_id="$(
            gh api \
              --method POST \
              repos/registrystack/registrystack-id/actions/workflows/deploy-cloudflare-workers.yml/dispatches \
              -f ref=main \
              -f "inputs[released_tag]=${{ needs.verify.outputs.tag }}" \
              -f "inputs[source_sha]=${{ needs.verify.outputs.source_sha }}" \
              -f "inputs[catalog_sha256]=${{ needs.verify.outputs.identifier_catalog_sha256 }}" \
              -f "inputs[request_id]=${request_id}" \
              -F return_run_details=true \
              --jq .workflow_run_id
          )"
          if [[ ! "${target_run_id}" =~ ^[1-9][0-9]*$ ]]; then
            echo "The identifier publication dispatch returned no run ID" >&2
            exit 1
          fi
          echo "Identifier publication run: https://github.com/registrystack/registrystack-id/actions/runs/${target_run_id}"
          gh run watch "${target_run_id}" \
            --repo registrystack/registrystack-id \
            --exit-status