name: Release

on:
  push:
    branches:
      - master
  schedule:
    # Nightly cut at 09:00 UTC, after the workday's merges have settled.
    - cron: "0 9 * * *"
  workflow_dispatch:
    inputs:
      channel:
        description: Release channel to publish
        required: true
        type: choice
        options:
          - stable
          - beta
          - nightly
        default: stable
      source_ref:
        description: (stable) Commit SHA, branch, or tag to publish as stable
        required: true
        type: string
        default: master
      stable_date:
        description: Enter a UTC date in YYYY-MM-DD format, for example 2026-03-18. Do not enter a version string. The workflow will resolve that date to a stable version such as 2026.318.0, then 2026.318.1 for the next same-day stable.
        required: false
        type: string
      source_version:
        description: For nightly, the explicit canary version to promote (empty selects the newest canary on master). For beta, the explicit nightly version to promote (empty selects the newest nightly on master).
        required: false
        type: string
      candidate_branch:
        description: (beta) candidate/beta-* branch to build a cherry-picked beta from. Leave empty to promote a nightly. Mutually exclusive with source_version.
        required: false
        type: string
      skip_soak_justification:
        description: (stable) Written justification for publishing a stable whose source has not soaked as a beta for 3 days. Leave empty for normal releases.
        required: false
        type: string
      dry_run:
        description: Preview the release without publishing
        required: true
        type: boolean
        default: false

concurrency:
  group: release-${{ github.event_name }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  verify_canary:
    if: github.event_name == 'push'
    uses: ./.github/workflows/release-verify.yml
    with:
      ref: ${{ github.sha }}

  publish_canary:
    if: github.event_name == 'push'
    needs: verify_canary
    runs-on: ubuntu-latest
    timeout-minutes: 45
    environment: npm-canary
    permissions:
      contents: write
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9.15.4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: pnpm

      - name: Validate release package manifest
        run: node ./scripts/release-package-map.mjs check

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Restore tracked install-time changes
        run: git checkout -- pnpm-lock.yaml

      - name: Configure git author
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Publish canary
        env:
          GITHUB_ACTIONS: "true"
        run: ./scripts/release.sh canary --skip-verify

      - name: Dump npm debug logs
        if: failure()
        run: |
          shopt -s nullglob
          for f in "$HOME"/.npm/_logs/*.log; do
            echo "===== $f ====="
            tail -n 300 "$f" | sed -E \
              -e 's#((authorization|_authToken|_auth|node_auth_token|npm_token)"?[[:space:]]*[:=][[:space:]]*"?)(Bearer[[:space:]]+)?[^",[:space:]]+#\1***REDACTED***#Ig'
          done

      - name: Push canary tag
        run: |
          tag="$(git tag --points-at HEAD | grep '^canary/v' | head -1)"
          if [ -z "$tag" ]; then
            echo "Error: no canary tag points at HEAD after release." >&2
            exit 1
          fi
          git push origin "refs/tags/${tag}"

  # ----- Nightly lane -----------------------------------------------------
  # Once a night (or on a forced nightly dispatch), promote the newest master
  # commit that already shipped a green canary: smoke-test that exact
  # published canary first, then republish the same commit under the nightly
  # identity. The candidate commit already passed release-verify during its
  # canary publish, so the nightly publish skips re-verification.

  select_nightly:
    if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'nightly')
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    outputs:
      proceed: ${{ steps.select.outputs.proceed }}
      sha: ${{ steps.select.outputs.sha }}
      canary_version: ${{ steps.select.outputs.canary_version }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: master
          fetch-depth: 0

      - name: Select nightly candidate
        id: select
        env:
          EXPLICIT_CANARY_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.source_version || '' }}
        run: |
          set -euo pipefail

          git fetch origin --tags --prune --quiet

          skip() {
            echo "proceed=false" >> "$GITHUB_OUTPUT"
            {
              echo "## Nightly skipped"
              echo ""
              echo "$1"
            } >> "$GITHUB_STEP_SUMMARY"
            echo "Nightly skipped: $1"
          }

          if [ -n "${EXPLICIT_CANARY_VERSION:-}" ]; then
            tag="canary/v${EXPLICIT_CANARY_VERSION}"
            sha="$(git rev-list -n 1 "$tag" 2>/dev/null || true)"
            if [ -z "$sha" ]; then
              echo "Error: tag $tag does not exist." >&2
              exit 1
            fi
          else
            # Newest canary-tagged commit on master. Canary tags are pushed
            # only after a successful canary publish, so tag presence is the
            # green-publish signal. Walk master newest-first and stop at the
            # first commit that carries a canary tag.
            sha="$(grep -m1 -F \
              -f <(git for-each-ref 'refs/tags/canary/v*' --format='%(objectname)') \
              <(git rev-list origin/master -n 500) || true)"

            if [ -z "$sha" ]; then
              skip "No canary/v* tag found on the last 500 commits of master."
              exit 0
            fi

            tag="$(git tag --points-at "$sha" | grep '^canary/v' | sort -V | tail -1)"
          fi

          canary_version="${tag#canary/v}"

          existing_nightly="$(git tag --points-at "$sha" | grep '^nightly/v' | head -1 || true)"
          if [ -n "$existing_nightly" ]; then
            skip "Candidate \`$sha\` (canary \`$canary_version\`) already shipped as \`$existing_nightly\`."
            exit 0
          fi

          # Promotions run the release tooling of the source commit, so the
          # source must already understand the nightly channel. (Literal match
          # of release.sh's channel case arm; if that line is reformatted this
          # fails closed and should be updated alongside it.)
          if ! git show "${sha}:scripts/release.sh" | grep -qF 'canary|nightly'; then
            echo "Error: source commit $sha predates nightly release tooling; promote a newer canary." >&2
            exit 1
          fi

          echo "proceed=true" >> "$GITHUB_OUTPUT"
          echo "sha=$sha" >> "$GITHUB_OUTPUT"
          echo "canary_version=$canary_version" >> "$GITHUB_OUTPUT"
          {
            echo "## Nightly candidate"
            echo ""
            echo "- Source SHA: \`$sha\`"
            echo "- Source canary: \`$canary_version\`"
          } >> "$GITHUB_STEP_SUMMARY"

  # Gate the promotion on the release smoke suite, run against the exact
  # published canary artifact that would become tonight's nightly. Red smoke
  # means no nightly tonight. Skipped for dry-run dispatches.
  smoke_nightly:
    needs: select_nightly
    if: needs.select_nightly.outputs.proceed == 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
    uses: ./.github/workflows/release-smoke.yml
    with:
      paperclip_version: ${{ needs.select_nightly.outputs.canary_version }}
      artifact_name: nightly-release-smoke

  publish_nightly:
    needs: [select_nightly, smoke_nightly]
    # Publish when smoke passed, or when smoke was deliberately skipped by a
    # dry-run dispatch (the publish itself is a dry-run in that case).
    if: >-
      !cancelled() &&
      needs.select_nightly.outputs.proceed == 'true' &&
      (needs.smoke_nightly.result == 'success' ||
       (needs.smoke_nightly.result == 'skipped' && github.event_name == 'workflow_dispatch' && inputs.dry_run))
    runs-on: ubuntu-latest
    timeout-minutes: 45
    environment: npm-canary
    # The workflow-level concurrency group is per event, so a forced dispatch
    # nightly could otherwise overlap the scheduled one and race it to the
    # same next -nightly.N version. Serialize actual nightly publishes across
    # events here; release.sh additionally refuses to double-publish a commit
    # that already carries a nightly tag.
    concurrency:
      group: release-publish-nightly
      cancel-in-progress: false
    permissions:
      contents: write
      id-token: write
      actions: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: ${{ needs.select_nightly.outputs.sha }}
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9.15.4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: pnpm

      - name: Validate release package manifest
        run: node ./scripts/release-package-map.mjs check

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Restore tracked install-time changes
        run: git checkout -- pnpm-lock.yaml

      - name: Configure git author
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Publish nightly
        env:
          GITHUB_ACTIONS: "true"
        run: |
          args=(nightly --skip-verify)
          if [ "${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}" = "true" ]; then
            args+=(--dry-run)
          fi
          ./scripts/release.sh "${args[@]}"

      - name: Dump npm debug logs
        if: failure()
        run: |
          shopt -s nullglob
          for f in "$HOME"/.npm/_logs/*.log; do
            echo "===== $f ====="
            tail -n 300 "$f" | sed -E \
              -e 's#((authorization|_authToken|_auth|node_auth_token|npm_token)"?[[:space:]]*[:=][[:space:]]*"?)(Bearer[[:space:]]+)?[^",[:space:]]+#\1***REDACTED***#Ig'
          done

      - name: Push nightly tag
        if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.dry_run) }}
        run: |
          tag="$(git tag --points-at HEAD | grep '^nightly/v' | head -1)"
          if [ -z "$tag" ]; then
            echo "Error: no nightly tag points at HEAD after release." >&2
            exit 1
          fi
          if ! git push origin "refs/tags/${tag}"; then
            sha="$(git rev-parse HEAD)"
            {
              echo "## Tag push rejected"
              echo ""
              echo "The npm publish succeeded, but pushing \`${tag}\` was rejected."
              echo "This usually means the tagged commit modifies workflow files,"
              echo "which GITHUB_TOKEN may not reference when creating refs from"
              echo "dispatch or scheduled runs. Recover with maintainer credentials:"
              echo ""
              echo '```'
              echo "git tag ${tag} ${sha}"
              echo "git push origin refs/tags/${tag}"
              echo "gh workflow run docker.yml --ref refs/tags/${tag}"
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
            echo "::error::Tag push rejected; see the job summary for recovery commands." >&2
            exit 1
          fi

      # Tag pushes made with GITHUB_TOKEN do not fire docker.yml's tag
      # trigger (GitHub suppresses workflow runs caused by GITHUB_TOKEN
      # pushes), so dispatch the image build at the new tag explicitly.
      - name: Build Docker images for the nightly tag
        if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.dry_run) }}
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          tag="$(git tag --points-at HEAD | grep '^nightly/v' | head -1)"
          {
            echo "## Nightly published"
            echo ""
            echo "- Source SHA: \`${{ needs.select_nightly.outputs.sha }}\`"
            echo "- Source canary: \`${{ needs.select_nightly.outputs.canary_version }}\`"
            echo "- Published nightly: \`${tag#nightly/v}\`"
            echo "- Docker build dispatched at \`${tag}\`"
          } >> "$GITHUB_STEP_SUMMARY"
          gh workflow run docker.yml --ref "refs/tags/${tag}" --repo "$GITHUB_REPOSITORY"

  # ----- Beta lane --------------------------------------------------------
  # Beta is a manual, human-approved promotion of a nightly. Unlike the
  # scheduled nightly lane, a beta dispatch is explicit operator intent, so
  # selection problems fail the run loudly instead of skipping quietly. The
  # publish runs behind the npm-beta environment, whose required reviewers
  # are the approval gate.

  select_beta:
    if: github.event_name == 'workflow_dispatch' && inputs.channel == 'beta'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    outputs:
      sha: ${{ steps.select.outputs.sha }}
      nightly_version: ${{ steps.select.outputs.nightly_version }}
      mode: ${{ steps.select.outputs.mode }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: master
          fetch-depth: 0

      - name: Select beta candidate
        id: select
        env:
          EXPLICIT_NIGHTLY_VERSION: ${{ inputs.source_version }}
          CANDIDATE_BRANCH: ${{ inputs.candidate_branch }}
        run: |
          set -euo pipefail

          git fetch origin --tags --prune --quiet

          # Candidate mode: build a cherry-picked beta from a short-lived
          # candidate branch instead of promoting a nightly.
          if [ -n "${CANDIDATE_BRANCH:-}" ]; then
            if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; then
              echo "Error: candidate_branch and source_version are mutually exclusive." >&2
              exit 1
            fi
            case "$CANDIDATE_BRANCH" in
              candidate/beta-*) ;;
              *)
                echo "Error: candidate branches must be named candidate/beta-<target> (got: $CANDIDATE_BRANCH)." >&2
                exit 1
                ;;
            esac
            git fetch origin "$CANDIDATE_BRANCH" --quiet
            sha="$(git rev-parse --verify "origin/${CANDIDATE_BRANCH}^{commit}" 2>/dev/null || true)"
            if [ -z "$sha" ]; then
              echo "Error: candidate branch $CANDIDATE_BRANCH does not exist on origin." >&2
              exit 1
            fi

            existing_beta="$(git tag --points-at "$sha" | grep '^beta/v' | head -1 || true)"
            if [ -n "$existing_beta" ]; then
              echo "Error: candidate head $sha already shipped as $existing_beta." >&2
              exit 1
            fi

            if ! git show "${sha}:scripts/release.sh" | grep -qF -- '--from-candidate'; then
              echo "Error: candidate head $sha predates candidate-build release tooling; rebase the candidate onto a newer base." >&2
              exit 1
            fi

            merge_base="$(git merge-base origin/master "$sha")"
            echo "mode=candidate" >> "$GITHUB_OUTPUT"
            echo "sha=$sha" >> "$GITHUB_OUTPUT"
            echo "nightly_version=" >> "$GITHUB_OUTPUT"
            {
              echo "## Beta candidate branch"
              echo ""
              echo "- Branch: \`$CANDIDATE_BRANCH\`"
              echo "- Head: \`$sha\`"
              echo "- Base (merge-base with master): \`$merge_base\`"
              echo "- Cherry-picked commits:"
              echo ""
              echo '\`\`\`'
              git log --oneline "${merge_base}..${sha}"
              echo '\`\`\`'
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          echo "mode=promote" >> "$GITHUB_OUTPUT"

          if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; then
            tag="nightly/v${EXPLICIT_NIGHTLY_VERSION}"
            sha="$(git rev-list -n 1 "$tag" 2>/dev/null || true)"
            if [ -z "$sha" ]; then
              echo "Error: tag $tag does not exist." >&2
              exit 1
            fi
          else
            # Newest nightly-tagged commit on master.
            sha="$(grep -m1 -F \
              -f <(git for-each-ref 'refs/tags/nightly/v*' --format='%(objectname)') \
              <(git rev-list origin/master -n 2000) || true)"

            if [ -z "$sha" ]; then
              echo "Error: no nightly/v* tag found on the last 2000 commits of master. Publish a nightly first, or pass source_version." >&2
              exit 1
            fi

            tag="$(git tag --points-at "$sha" | grep '^nightly/v' | sort -V | tail -1)"
          fi

          nightly_version="${tag#nightly/v}"

          existing_beta="$(git tag --points-at "$sha" | grep '^beta/v' | head -1 || true)"
          if [ -n "$existing_beta" ]; then
            echo "Error: candidate $sha (nightly $nightly_version) already shipped as $existing_beta." >&2
            exit 1
          fi

          # Promotions run the release tooling of the source commit, so the
          # source must already understand the beta channel. (Literal match of
          # release.sh's channel case arm; if that line is reformatted this
          # fails closed and should be updated alongside it.)
          if ! git show "${sha}:scripts/release.sh" | grep -qF 'canary|nightly|beta|stable)'; then
            echo "Error: source commit $sha predates beta release tooling; promote a newer nightly whose source contains the beta channel." >&2
            exit 1
          fi

          echo "sha=$sha" >> "$GITHUB_OUTPUT"
          echo "nightly_version=$nightly_version" >> "$GITHUB_OUTPUT"
          {
            echo "## Beta candidate"
            echo ""
            echo "- Source SHA: \`$sha\`"
            echo "- Source nightly: \`$nightly_version\`"
          } >> "$GITHUB_STEP_SUMMARY"

  # Candidate-branch heads are new commits that never went through a canary
  # or nightly, so they must pass full verification before publishing.
  # Promoted nightlies were already verified by their canary run and skip it.
  verify_beta_candidate:
    needs: select_beta
    if: needs.select_beta.outputs.mode == 'candidate'
    uses: ./.github/workflows/release-verify.yml
    with:
      ref: ${{ needs.select_beta.outputs.sha }}

  publish_beta:
    needs: [select_beta, verify_beta_candidate]
    if: >-
      !cancelled() &&
      needs.select_beta.result == 'success' &&
      (needs.verify_beta_candidate.result == 'success' ||
       (needs.verify_beta_candidate.result == 'skipped' && needs.select_beta.outputs.mode == 'promote'))
    runs-on: ubuntu-latest
    timeout-minutes: 45
    environment: npm-beta
    # Serialize beta publishes so two dispatches cannot race to the same next
    # -beta.N version; release.sh additionally refuses to double-publish a
    # commit that already carries a beta tag.
    concurrency:
      group: release-publish-beta
      cancel-in-progress: false
    permissions:
      contents: write
      id-token: write
      actions: write
    outputs:
      beta_version: ${{ steps.result.outputs.beta_version }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: ${{ needs.select_beta.outputs.sha }}
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9.15.4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: pnpm

      - name: Validate release package manifest
        run: node ./scripts/release-package-map.mjs check

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Restore tracked install-time changes
        run: git checkout -- pnpm-lock.yaml

      - name: Configure git author
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Publish beta
        env:
          GITHUB_ACTIONS: "true"
        run: |
          args=(beta --skip-verify)
          if [ "${{ needs.select_beta.outputs.mode }}" = "candidate" ]; then
            args+=(--from-candidate)
          fi
          if [ "${{ inputs.dry_run }}" = "true" ]; then
            args+=(--dry-run)
          fi
          ./scripts/release.sh "${args[@]}"

      - name: Dump npm debug logs
        if: failure()
        run: |
          shopt -s nullglob
          for f in "$HOME"/.npm/_logs/*.log; do
            echo "===== $f ====="
            tail -n 300 "$f" | sed -E \
              -e 's#((authorization|_authToken|_auth|node_auth_token|npm_token)"?[[:space:]]*[:=][[:space:]]*"?)(Bearer[[:space:]]+)?[^",[:space:]]+#\1***REDACTED***#Ig'
          done

      - name: Push beta tag
        if: ${{ !inputs.dry_run }}
        run: |
          tag="$(git tag --points-at HEAD | grep '^beta/v' | head -1)"
          if [ -z "$tag" ]; then
            echo "Error: no beta tag points at HEAD after release." >&2
            exit 1
          fi
          if ! git push origin "refs/tags/${tag}"; then
            sha="$(git rev-parse HEAD)"
            {
              echo "## Tag push rejected"
              echo ""
              echo "The npm publish succeeded, but pushing \`${tag}\` was rejected."
              echo "This usually means the tagged commit modifies workflow files,"
              echo "which GITHUB_TOKEN may not reference when creating refs from"
              echo "dispatch or scheduled runs. Recover with maintainer credentials:"
              echo ""
              echo '```'
              echo "git tag ${tag} ${sha}"
              echo "git push origin refs/tags/${tag}"
              echo "gh workflow run docker.yml --ref refs/tags/${tag}"
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
            echo "::error::Tag push rejected; see the job summary for recovery commands." >&2
            exit 1
          fi

      # Tag pushes made with GITHUB_TOKEN do not fire docker.yml's tag
      # trigger (GitHub suppresses workflow runs caused by GITHUB_TOKEN
      # pushes), so dispatch the image build at the new tag explicitly.
      - name: Build Docker images for the beta tag
        id: result
        if: ${{ !inputs.dry_run }}
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          tag="$(git tag --points-at HEAD | grep '^beta/v' | head -1)"
          echo "beta_version=${tag#beta/v}" >> "$GITHUB_OUTPUT"
          {
            echo "## Beta published"
            echo ""
            echo "- Source SHA: \`${{ needs.select_beta.outputs.sha }}\`"
            echo "- Source nightly: \`${{ needs.select_beta.outputs.nightly_version }}\`"
            echo "- Published beta: \`${tag#beta/v}\`"
            echo "- Docker build dispatched at \`${tag}\`"
          } >> "$GITHUB_STEP_SUMMARY"
          gh workflow run docker.yml --ref "refs/tags/${tag}" --repo "$GITHUB_REPOSITORY"

  # Post-publish verification: run the release smoke suite against the exact
  # beta version that was just published.
  smoke_beta:
    needs: publish_beta
    if: ${{ !inputs.dry_run }}
    uses: ./.github/workflows/release-smoke.yml
    with:
      paperclip_version: ${{ needs.publish_beta.outputs.beta_version }}
      artifact_name: beta-release-smoke

  # ----- Stable lane ------------------------------------------------------

  # Stable releases promote a soaked beta. The preflight enforces that the
  # source commit shipped as a beta at least 3 days ago (measured from the
  # npm publish time of that beta version), unless a written justification
  # is provided. Dry runs report soak state without blocking.
  # Resolves source_ref to an immutable commit exactly once; every downstream
  # stable job consumes that SHA. Otherwise a branch or movable tag that
  # advances mid-run could be soak-checked at one commit and verified or
  # published at another.
  preflight_stable:
    if: github.event_name == 'workflow_dispatch' && inputs.channel == 'stable'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    outputs:
      sha: ${{ steps.soak.outputs.sha }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          ref: master
          fetch-depth: 0

      - name: Check beta soak
        id: soak
        env:
          SOURCE_REF: ${{ inputs.source_ref }}
          JUSTIFICATION: ${{ inputs.skip_soak_justification }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -euo pipefail

          git fetch origin --tags --prune --quiet

          sha="$(git rev-parse --verify "${SOURCE_REF}^{commit}" 2>/dev/null || true)"
          if [ -z "$sha" ]; then
            git fetch origin "$SOURCE_REF" --quiet || true
            sha="$(git rev-parse --verify "FETCH_HEAD^{commit}" 2>/dev/null || true)"
          fi
          if [ -z "$sha" ]; then
            echo "Error: could not resolve source_ref '$SOURCE_REF' to a commit." >&2
            exit 1
          fi

          echo "sha=$sha" >> "$GITHUB_OUTPUT"
          {
            echo "## Stable source pinned"
            echo ""
            echo "- source_ref: \`${SOURCE_REF}\` -> \`$sha\`"
          } >> "$GITHUB_STEP_SUMMARY"

          fail_or_justify() {
            if [ -n "${JUSTIFICATION:-}" ]; then
              {
                echo "## Stable soak gate bypassed"
                echo ""
                echo "$1"
                echo ""
                echo "Justification: ${JUSTIFICATION}"
              } >> "$GITHUB_STEP_SUMMARY"
              echo "::warning::Soak gate bypassed: $1"
              return 0
            fi
            if [ "${DRY_RUN}" = "true" ]; then
              echo "::warning::Soak gate would block a real release: $1"
              {
                echo "## Stable soak gate (dry run)"
                echo ""
                echo "A real release would be blocked: $1"
              } >> "$GITHUB_STEP_SUMMARY"
              return 0
            fi
            echo "Error: $1" >&2
            echo "Pass skip_soak_justification with a written reason to release anyway." >&2
            exit 1
          }

          beta_tag="$(git tag --points-at "$sha" | grep '^beta/v' | sort -V | tail -1 || true)"
          if [ -z "$beta_tag" ]; then
            fail_or_justify "source commit $sha never shipped as a beta (no beta/v* tag)."
            exit 0
          fi

          beta_version="${beta_tag#beta/v}"
          publish_time="$(npm view "paperclipai@${beta_version}" time --json 2>/dev/null \
            | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{const t=JSON.parse(d);process.stdout.write(typeof t === "string" ? t : (t[process.argv[1]] ?? ""))})' "$beta_version" || true)"
          if [ -z "$publish_time" ]; then
            fail_or_justify "could not determine the npm publish time of beta ${beta_version}."
            exit 0
          fi

          age_seconds="$(node -e 'process.stdout.write(String(Math.floor((Date.now() - Date.parse(process.argv[1])) / 1000)))' "$publish_time")"
          min_seconds=$((3 * 24 * 60 * 60))
          age_days="$(node -e 'process.stdout.write((Number(process.argv[1]) / 86400).toFixed(1))' "$age_seconds")"

          if [ "$age_seconds" -lt "$min_seconds" ]; then
            fail_or_justify "beta ${beta_version} has only soaked ${age_days} days (minimum is 3)."
            exit 0
          fi

          {
            echo "## Stable soak gate passed"
            echo ""
            echo "- Source beta: \`${beta_version}\`"
            echo "- Soak time: ${age_days} days"
          } >> "$GITHUB_STEP_SUMMARY"

  verify_stable:
    if: github.event_name == 'workflow_dispatch' && inputs.channel == 'stable'
    needs: preflight_stable
    uses: ./.github/workflows/release-verify.yml
    with:
      ref: ${{ needs.preflight_stable.outputs.sha }}

  preview_stable:
    if: github.event_name == 'workflow_dispatch' && inputs.channel == 'stable' && inputs.dry_run
    needs: [preflight_stable, verify_stable]
    runs-on: ubuntu-latest
    timeout-minutes: 45
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ needs.preflight_stable.outputs.sha }}

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9.15.4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: pnpm

      - name: Validate release package manifest
        run: node ./scripts/release-package-map.mjs check

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Dry-run stable release
        env:
          GITHUB_ACTIONS: "true"
        run: |
          args=(stable --skip-verify --dry-run)
          if [ -n "${{ inputs.stable_date }}" ]; then
            args+=(--date "${{ inputs.stable_date }}")
          fi
          ./scripts/release.sh "${args[@]}"

  publish_stable:
    if: github.event_name == 'workflow_dispatch' && inputs.channel == 'stable' && !inputs.dry_run
    needs: [preflight_stable, verify_stable]
    runs-on: ubuntu-latest
    timeout-minutes: 45
    environment: npm-stable
    permissions:
      contents: write
      id-token: write
      actions: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ needs.preflight_stable.outputs.sha }}

      - name: Setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 9.15.4

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --no-frozen-lockfile

      - name: Restore tracked install-time changes
        run: git checkout -- pnpm-lock.yaml

      - name: Configure git author
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Publish stable
        env:
          GITHUB_ACTIONS: "true"
        run: |
          args=(stable --skip-verify)
          if [ -n "${{ inputs.stable_date }}" ]; then
            args+=(--date "${{ inputs.stable_date }}")
          fi
          ./scripts/release.sh "${args[@]}"

      - name: Dump npm debug logs
        if: failure()
        run: |
          shopt -s nullglob
          for f in "$HOME"/.npm/_logs/*.log; do
            echo "===== $f ====="
            tail -n 300 "$f" | sed -E \
              -e 's#((authorization|_authToken|_auth|node_auth_token|npm_token)"?[[:space:]]*[:=][[:space:]]*"?)(Bearer[[:space:]]+)?[^",[:space:]]+#\1***REDACTED***#Ig'
          done

      - name: Push stable tag
        run: |
          tag="$(git tag --points-at HEAD | grep '^v' | head -1)"
          if [ -z "$tag" ]; then
            echo "Error: no stable tag points at HEAD after release." >&2
            exit 1
          fi
          if ! git push origin "refs/tags/${tag}"; then
            sha="$(git rev-parse HEAD)"
            {
              echo "## Tag push rejected"
              echo ""
              echo "The npm publish succeeded, but pushing \`${tag}\` was rejected."
              echo "This usually means the tagged commit modifies workflow files,"
              echo "which GITHUB_TOKEN may not reference when creating refs from"
              echo "dispatch or scheduled runs. Recover with maintainer credentials:"
              echo ""
              echo '```'
              echo "git tag ${tag} ${sha}"
              echo "git push origin refs/tags/${tag}"
              echo "gh workflow run docker.yml --ref refs/tags/${tag}"
            echo "./scripts/create-github-release.sh ${tag#v}"
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
            echo "::error::Tag push rejected; see the job summary for recovery commands." >&2
            exit 1
          fi

      # Tag pushes made with GITHUB_TOKEN do not fire docker.yml's tag
      # trigger (GitHub suppresses workflow runs caused by GITHUB_TOKEN
      # pushes), so dispatch the image build at the new tag explicitly. This
      # is what moves Docker `:latest` and publishes the versioned stable
      # image tags.
      - name: Build Docker images for the stable tag
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          tag="$(git tag --points-at HEAD | grep '^v' | head -1)"
          if gh workflow run docker.yml --ref "refs/tags/${tag}" --repo "$GITHUB_REPOSITORY"; then
            echo "Dispatched docker.yml at ${tag}."
          else
            # Older source commits may predate docker.yml's workflow_dispatch
            # trigger; the dispatch then fails while the npm release is
            # already complete and correct.
            echo "::warning::Could not dispatch docker.yml at ${tag}. Run docker.yml manually at that tag to publish the stable images."
          fi

      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
          PUBLISH_REMOTE: origin
        run: |
          version="$(git tag --points-at HEAD | grep '^v' | head -1 | sed 's/^v//')"
          if [ -z "$version" ]; then
            echo "Error: no v* tag points at HEAD after stable release." >&2
            exit 1
          fi
          ./scripts/create-github-release.sh "$version"