cd.yml

name: 🚀 Release Beta

on:
  push:
    branches: [master]
  workflow_dispatch:
    inputs:
      publish_only:
        description: "Finalize beta artifacts from already-merged manifests"
        required: true
        type: boolean
        default: false
      projects:
        description: "Comma-separated Nx release project names"
        required: false
        type: string
      expected_sha:
        description: "Full current master SHA; required for publish-only finalization"
        required: false
        type: string

concurrency:
  group: release-beta
  cancel-in-progress: false

env:
  DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/effectify"

jobs:
  release-beta:
    name: 🚀 Release Beta
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: effectify
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - name: 📥 Checkout
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: 📦 Install pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 10.14.0

      - name: 🏗️ Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "24.19.0"
          cache: "pnpm"
          registry-url: "https://registry.npmjs.org/"

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

      - name: 🛡️ Verify release policy contract
        run: node --test scripts/release-policy-contract.test.mjs

      - name: 🧭 Resolve beta mode and projects
        id: release
        env:
          EVENT_NAME: ${{ github.event_name }}
          PUBLISH_ONLY: ${{ inputs.publish_only || false }}
          REQUESTED_PROJECTS: ${{ inputs.projects || '' }}
          EXPECTED_SHA: ${{ inputs.expected_sha || '' }}
          BEFORE_SHA: ${{ github.event.before }}
          HEAD_SHA: ${{ github.sha }}
          HEAD_MESSAGE: ${{ github.event.head_commit.message || '' }}
        run: |
          set -euo pipefail
          RELEASE_PROJECTS=$(
            jq -r '.release.projects[]' nx.json | while read -r RELEASE_ROOT; do
              pnpm nx show project "$RELEASE_ROOT" --json | jq -r '.name'
            done | jq -Rsc 'split("\n") | map(select(length > 0)) | unique'
          )
          ALL_PROJECTS=$(printf '%s' "$RELEASE_PROJECTS" | jq -r '.[]' | sort)
          test -n "$ALL_PROJECTS" || { echo "Nx release project allowlist is empty" >&2; exit 1; }

          select_requested_projects() {
            test -n "$REQUESTED_PROJECTS" || { echo "manual beta runs require explicit projects" >&2; exit 1; }
            RAW_PROJECTS=$(printf '%s' "$REQUESTED_PROJECTS" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sed '/^$/d')
            test -n "$RAW_PROJECTS" || { echo "manual beta runs require nonempty projects" >&2; exit 1; }
            DUPLICATES=$(printf '%s\n' "$RAW_PROJECTS" | sort | uniq -d)
            test -z "$DUPLICATES" || { echo "duplicate release project: $DUPLICATES" >&2; exit 1; }
            SELECTED_PROJECTS=$(printf '%s\n' "$RAW_PROJECTS" | sort)
            while IFS= read -r project; do
              printf '%s\n' "$ALL_PROJECTS" | grep -Fx -- "$project" >/dev/null || {
                echo "Invalid release project: $project" >&2
                exit 1
              }
            done <<< "$SELECTED_PROJECTS"
          }

          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            select_requested_projects
            if [ "$PUBLISH_ONLY" = "true" ]; then
              [[ "$EXPECTED_SHA" =~ ^[0-9a-f]{40}$ ]] || {
                echo "FINALIZE requires a full lowercase expected_sha" >&2
                exit 1
              }
              echo "mode=finalize" >> "$GITHUB_OUTPUT"
            else
              echo "version_specifier=" >> "$GITHUB_OUTPUT"
              echo "mode=prepare" >> "$GITHUB_OUTPUT"
            fi
            echo "has_projects=true" >> "$GITHUB_OUTPUT"
            echo "projects=$(printf '%s' "$SELECTED_PROJECTS" | paste -sd, -)" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          ZERO_SHA="0000000000000000000000000000000000000000"
          [[ "$BEFORE_SHA" =~ ^[0-9a-f]{40}$ ]] && [ "$BEFORE_SHA" != "$ZERO_SHA" ] || {
            echo "master push requires a nonzero full lowercase before SHA" >&2
            exit 1
          }
          [[ "$HEAD_SHA" =~ ^[0-9a-f]{40}$ ]] && [ "$HEAD_SHA" != "$ZERO_SHA" ] || {
            echo "master push requires a nonzero full lowercase head SHA" >&2
            exit 1
          }
          BEFORE="$BEFORE_SHA"
          HEAD="$HEAD_SHA"
          test "$(git cat-file -t "$BEFORE" 2>/dev/null)" = "commit" || {
            echo "master push before SHA is not a commit object" >&2
            exit 1
          }
          test "$(git cat-file -t "$HEAD" 2>/dev/null)" = "commit" || {
            echo "master push head SHA is not a commit object" >&2
            exit 1
          }
          test "$(git rev-parse HEAD)" = "$HEAD" || {
            echo "checked-out HEAD does not match the master push head SHA" >&2
            exit 1
          }
          BASE="$BEFORE"

          CHANGED=$(mktemp); git diff --name-only --no-renames "$BASE" "$HEAD" | sort -u > "$CHANGED"
          RELEASE_MANIFESTS=$(mktemp)
          jq -r '.release.projects[]' nx.json | while read -r RELEASE_ROOT; do
            DATA=$(pnpm nx show project "$RELEASE_ROOT" --json)
            ROOT=$(printf '%s' "$DATA" | jq -er '.root | select(type == "string" and length > 0)')
            NAME=$(printf '%s' "$DATA" | jq -er '.name | select(type == "string" and length > 0)')
            test "$ROOT" = "$RELEASE_ROOT" || { echo "release project root mismatch for $NAME" >&2; exit 1; }
            printf '%s\t%s/package.json\n' "$NAME" "$ROOT"
          done | sort -k2,2 > "$RELEASE_MANIFESTS"
          test -s "$RELEASE_MANIFESTS" || { echo "release manifest allowlist is empty" >&2; exit 1; }

          HEAD_SUBJECT=${HEAD_MESSAGE%%$'\n'*}
          # release-policy-classifier:start
          classify_push_shape() {
            HAS_CHANGELOG=false
            UNEXPECTED=false
            MANIFEST_CHANGES=0
            BENIGN_MANIFEST_CHANGES=0
            BETA_TRANSITIONS=0
            INVALID_MANIFESTS=0
            while IFS= read -r CHANGED_PATH; do
              if [ "$CHANGED_PATH" = "CHANGELOG.md" ]; then
                if ! CHANGELOG_TYPE=$(git cat-file -t "$HEAD:CHANGELOG.md" 2>/dev/null) || [ "$CHANGELOG_TYPE" != "blob" ]; then
                  INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                  continue
                fi
                HAS_CHANGELOG=true
                continue
              fi
              if ! RECORD=$(awk -F '\t' -v manifest="$CHANGED_PATH" '$2 == manifest { print }' "$RELEASE_MANIFESTS"); then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              if [ -z "$RECORD" ]; then
                UNEXPECTED=true
                continue
              fi
              if [[ "$RECORD" == *$'\n'* ]]; then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              NAME=${RECORD%%$'\t'*}
              MANIFEST_PATH=${RECORD#*$'\t'}
              MANIFEST_CHANGES=$((MANIFEST_CHANGES + 1))
              if ! OLD_DOCUMENT=$(git show "$BASE:$MANIFEST_PATH" 2>/dev/null) ||
                 ! NEW_DOCUMENT=$(git show "$HEAD:$MANIFEST_PATH" 2>/dev/null); then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              if ! printf '%s' "$OLD_DOCUMENT" | jq -e -s 'length == 1 and (.[0] | type == "object")' >/dev/null 2>&1 ||
                 ! printf '%s' "$NEW_DOCUMENT" | jq -e -s 'length == 1 and (.[0] | type == "object")' >/dev/null 2>&1; then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              if ! OLD_NAME=$(printf '%s' "$OLD_DOCUMENT" | jq -er '.name | select(type == "string" and length > 0)' 2>/dev/null) ||
                 ! OLD_VERSION=$(printf '%s' "$OLD_DOCUMENT" | jq -er '.version | select(type == "string" and length > 0)' 2>/dev/null) ||
                 ! NEW_NAME=$(printf '%s' "$NEW_DOCUMENT" | jq -er '.name | select(type == "string" and length > 0)' 2>/dev/null) ||
                 ! NEW_VERSION=$(printf '%s' "$NEW_DOCUMENT" | jq -er '.version | select(type == "string" and length > 0)' 2>/dev/null); then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              if [ "$OLD_NAME" != "$NAME" ] || [ "$NEW_NAME" != "$NAME" ]; then
                INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
                continue
              fi
              if [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
                BENIGN_MANIFEST_CHANGES=$((BENIGN_MANIFEST_CHANGES + 1))
                continue
              fi
              if [[ "$OLD_VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)-beta\.(0|[1-9][0-9]*)$ ]]; then
                STABLE_VERSION="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.${BASH_REMATCH[3]}"
                if [ "$NEW_VERSION" = "$STABLE_VERSION" ]; then
                  BETA_TRANSITIONS=$((BETA_TRANSITIONS + 1))
                  continue
                fi
              fi
              INVALID_MANIFESTS=$((INVALID_MANIFESTS + 1))
            done < "$CHANGED"

            if [ "$HAS_CHANGELOG" = "true" ] && [ "$UNEXPECTED" = "false" ] && [ "$INVALID_MANIFESTS" = "0" ] && [ "$BETA_TRANSITIONS" -gt 0 ] && [ "$BETA_TRANSITIONS" -eq "$MANIFEST_CHANGES" ]; then
              printf '%s\n' suppress
              return
            fi
            if [[ "$HEAD_SUBJECT" == *"chore(release):"* || "$HEAD_SUBJECT" == *"[skip release]"* ]]; then
              printf '%s\n' reject
              return
            fi
            if [ "$HAS_CHANGELOG" = "true" ] || [ "$INVALID_MANIFESTS" -gt 0 ] || [ "$BETA_TRANSITIONS" -gt 0 ] || [ "$MANIFEST_CHANGES" -ne "$BENIGN_MANIFEST_CHANGES" ]; then
              printf '%s\n' reject
              return
            fi
            printf '%s\n' prepare
          }
          # release-policy-classifier:end

          CLASSIFICATION=$(classify_push_shape)
          if [ "$CLASSIFICATION" = "suppress" ]; then
            echo "mode=suppress" >> "$GITHUB_OUTPUT"; echo "has_projects=false" >> "$GITHUB_OUTPUT"; echo "projects=" >> "$GITHUB_OUTPUT"; exit 0
          fi
          if [ "$CLASSIFICATION" != "prepare" ]; then
            echo "stable promotion shape is partial, mixed, or malformed" >&2
            echo "suspicious release-shaped master push; refusing preparation" >&2
            exit 1
          fi

          AFFECTED_RAW=$(pnpm nx show projects --affected --base="$BASE" --head="$HEAD" --json)
          printf '%s' "$AFFECTED_RAW" | jq -e -s 'length == 1 and (.[0] | type == "array" and all(.[]; type == "string"))' >/dev/null
          AFFECTED_RELEASE_PROJECTS=$(printf '%s' "$AFFECTED_RAW" | jq -r --argjson release "$RELEASE_PROJECTS" '[.[] | select(. as $project | $release | index($project))] | unique | join(",")')
          if [ -z "$AFFECTED_RELEASE_PROJECTS" ] || [ "$AFFECTED_RELEASE_PROJECTS" = "null" ]; then
            echo "mode=prepare" >> "$GITHUB_OUTPUT"
            echo "has_projects=false" >> "$GITHUB_OUTPUT"
            echo "projects=" >> "$GITHUB_OUTPUT"
          else
            echo "mode=prepare" >> "$GITHUB_OUTPUT"
            echo "has_projects=true" >> "$GITHUB_OUTPUT"
            echo "projects=$AFFECTED_RELEASE_PROJECTS" >> "$GITHUB_OUTPUT"
          fi

      - name: 🔧 Configure Git for release
        if: ${{ (steps.release.outputs.mode == 'prepare' || steps.release.outputs.mode == 'finalize') && steps.release.outputs.has_projects == 'true' }}
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: 🏗️ Build selected projects
        if: ${{ steps.release.outputs.mode != 'suppress' && steps.release.outputs.has_projects == 'true' }}
        env:
          PROJECTS: ${{ steps.release.outputs.projects }}
        run: pnpm nx run-many -t build "--projects=$PROJECTS" --parallel=3

      - name: 🧪 Test selected projects
        if: ${{ steps.release.outputs.mode != 'suppress' && steps.release.outputs.has_projects == 'true' }}
        env:
          PROJECTS: ${{ steps.release.outputs.projects }}
        run: pnpm nx run-many -t test "--projects=$PROJECTS" --parallel=3 --passWithNoTests

      - name: ✅ Verify React Router 8 readiness
        if: ${{ steps.release.outputs.mode != 'suppress' && steps.release.outputs.has_projects == 'true' }}
        run: |
          pnpm nx test @effectify/react-router
          pnpm nx run @effectify/react-router-example:migration:test
          pnpm nx run @effectify/react-router-example:migration:verify
          pnpm nx run @effectify/react-router-example:migration:manifest
          pnpm nx run @effectify/react-router-example:consolidation:verify

      - name: 🌿 PREPARE verified beta branch
        id: prepare
        if: ${{ steps.release.outputs.mode == 'prepare' && steps.release.outputs.has_projects == 'true' }}
        env:
          PROJECTS: ${{ steps.release.outputs.projects }}
          VERSION_SPECIFIER: ${{ steps.release.outputs.version_specifier }}
        run: |
          set -euo pipefail
          SOURCE_SHA=$(git rev-parse HEAD)
          SOURCE_REF="$GITHUB_REF"
          SHA_PREFIX=${SOURCE_SHA:0:12}
          RELEASE_BRANCH="release/beta-$SHA_PREFIX"
          git switch --create "$RELEASE_BRANCH"
          REFS_BEFORE=$(git for-each-ref --format='%(refname) %(objectname)' refs/heads refs/tags | sort)

          RELEASE_PATHS=("CHANGELOG.md")
          RECORDS=$(mktemp)
          IFS=',' read -ra SELECTED <<< "$PROJECTS"
          for project in "${SELECTED[@]}"; do
            DATA=$(pnpm nx show project "$project" --json)
            ROOT=$(printf '%s' "$DATA" | jq -er '.root | select(length > 0)')
            NAME=$(printf '%s' "$DATA" | jq -er '.name | select(length > 0)')
            MANIFEST="$ROOT/package.json"
            RELEASE_PATHS+=("$MANIFEST")
            printf '%s\t%s\t%s\n' "$project" "$NAME" "$MANIFEST" >> "$RECORDS"
          done
          printf '%s\n' "${RELEASE_PATHS[@]}" | sort -u > /tmp/expected-release-paths
          test "$(wc -l < /tmp/expected-release-paths | tr -d ' ')" = "$(( ${#SELECTED[@]} + 1 ))"

          pnpm nx release version $VERSION_SPECIFIER "--projects=$PROJECTS" --preid=beta --git-commit=false --git-tag=false --git-push=false --stage-changes=false

          verify_prepared_tree() {
            ACTUAL_PATHS=$(mktemp)
            { git diff --name-only --no-renames HEAD; git ls-files --others --exclude-standard; } | sort -u > "$ACTUAL_PATHS"
            cmp -s /tmp/expected-release-paths "$ACTUAL_PATHS" || {
              echo "PREPARE changed paths differ from selected manifests plus root CHANGELOG.md" >&2
              diff -u /tmp/expected-release-paths "$ACTUAL_PATHS" >&2 || true
              exit 1
            }
            test "$REFS_BEFORE" = "$(git for-each-ref --format='%(refname) %(objectname)' refs/heads refs/tags | sort)" || {
              echo "PREPARE materialization changed a git ref" >&2
              exit 1
            }
            while IFS=$'\t' read -r project name manifest; do
              VERSION=$(jq -er '.version' "$manifest")
              [[ "$VERSION" =~ -beta\.[0-9]+$ ]] || { echo "$name did not materialize a beta version" >&2; exit 1; }
            done < "$RECORDS"
          }
          verify_prepared_tree

          pnpm nx run-many -t build "--projects=$PROJECTS" --parallel=3
          verify_prepared_tree
          git add --pathspec-from-file=/tmp/expected-release-paths
          git diff --cached --name-only --no-renames | sort -u > /tmp/staged-release-paths
          if ! cmp -s /tmp/expected-release-paths /tmp/staged-release-paths; then
            echo "::error::expected=$(paste -sd, /tmp/expected-release-paths); actual=$(paste -sd, /tmp/staged-release-paths)"
            exit 1
          fi
          git diff --quiet
          test -z "$(git ls-files --others --exclude-standard)"
          verify_prepared_tree
          if ! git commit -m "chore(release): prepare beta from $SOURCE_SHA [skip release]"; then
            echo "::error::PREPARE local commit failed"
            exit 1
          fi
          if ! test -z "$(git status --porcelain)"; then
            echo "::error::PREPARE post-commit tree dirty"
            exit 1
          fi
          if ! git push origin "HEAD:refs/heads/release/beta-$SHA_PREFIX"; then
            echo "::error::PREPARE release-branch push failed"
            exit 1
          fi
          VERSIONS=$(while IFS=$'\t' read -r project name manifest; do printf '%s=%s\n' "$name" "$(jq -er '.version' "$manifest")"; done < "$RECORDS" | paste -sd, -)
          CHANGED_PATHS=$(paste -sd, /tmp/expected-release-paths)
          echo "source_sha=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
          echo "source_ref=$SOURCE_REF" >> "$GITHUB_OUTPUT"
          echo "branch=$RELEASE_BRANCH" >> "$GITHUB_OUTPUT"
          echo "versions=$VERSIONS" >> "$GITHUB_OUTPUT"
          echo "changed_paths=$CHANGED_PATHS" >> "$GITHUB_OUTPUT"

      - name: 🔐 Verify npm authentication for FINALIZE
        if: ${{ steps.release.outputs.mode == 'finalize' && steps.release.outputs.has_projects == 'true' }}
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm whoami

      - name: 🚀 FINALIZE exact merged beta
        if: ${{ steps.release.outputs.mode == 'finalize' && steps.release.outputs.has_projects == 'true' }}
        env:
          PROJECTS: ${{ steps.release.outputs.projects }}
          EXPECTED_SHA: ${{ inputs.expected_sha }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_CONFIG_PROVENANCE: true
        run: |
          set -euo pipefail
          git fetch origin master:refs/remotes/origin/master --no-tags
          HEAD_SHA=$(git rev-parse HEAD)
          REMOTE_SHA=$(git rev-parse origin/master)
          test "$HEAD_SHA" = "$EXPECTED_SHA"
          test "$REMOTE_SHA" = "$EXPECTED_SHA"

          RECORDS=$(mktemp)
          IFS=',' read -ra SELECTED <<< "$PROJECTS"
          for PROJECT in "${SELECTED[@]}"; do
            DATA=$(pnpm nx show project "$PROJECT" --json)
            ROOT=$(printf '%s' "$DATA" | jq -er '.root | select(length > 0)')
            MANIFEST="$ROOT/package.json"
            NAME=$(jq -er '.name | select(length > 0)' "$MANIFEST")
            VERSION=$(jq -er '.version | select(length > 0)' "$MANIFEST")
            test "$VERSION" != "${VERSION%-beta.*}"
            [[ "$VERSION" =~ -beta\.[0-9]+$ ]]
            TAG="$NAME@$VERSION"
            printf '%s\t%s\t%s\t%s\t%s\n' "$PROJECT" "$MANIFEST" "$NAME" "$VERSION" "$TAG" >> "$RECORDS"
          done
          test "$(sort -u -k3,3 "$RECORDS" | wc -l | tr -d ' ')" = "${#SELECTED[@]}"

          : > /tmp/missing-projects
          while IFS=$'\t' read -r PROJECT MANIFEST NAME VERSION TAG; do
            VERSIONS_JSON=$(npm view "$NAME" versions --json) || { echo "unknown npm history for $NAME" >&2; exit 1; }
            printf '%s' "$VERSIONS_JSON" | jq -e 'type == "array" or type == "string"' >/dev/null
            BETA_TAG=$(npm view "$NAME" dist-tags.beta --json | jq -r 'if . == null then "" else . end') || {
              echo "unknown npm beta tag for $NAME" >&2
              exit 1
            }
            if printf '%s' "$VERSIONS_JSON" | jq -e --arg version "$VERSION" 'if type == "array" then index($version) != null else . == $version end' >/dev/null; then
              test "$BETA_TAG" = "$VERSION" || { echo "conflicting npm beta state for $NAME" >&2; exit 1; }
            else
              printf '%s\n' "$PROJECT" >> /tmp/missing-projects
            fi
          done < "$RECORDS"

          verify_tags() {
            MODE=$1
            [ "$MODE" != "collect" ] || : > /tmp/missing-tags
            while IFS=$'\t' read -r PROJECT MANIFEST NAME VERSION TAG; do
              REMOTE_TAGS=$(git ls-remote --tags origin "refs/tags/$TAG" "refs/tags/$TAG^{}") || {
                echo "unknown remote tag state for $TAG" >&2
                exit 1
              }
              if [ -z "$REMOTE_TAGS" ]; then
                [ "$MODE" = "collect" ] || { echo "missing pushed tag $TAG" >&2; exit 1; }
                printf '%s\n' "$TAG" >> /tmp/missing-tags
                continue
              fi
              DIRECT_COUNT=$(printf '%s\n' "$REMOTE_TAGS" | grep -c $'\trefs/tags/'"$TAG"'$' || true)
              PEELED_COUNT=$(printf '%s\n' "$REMOTE_TAGS" | grep -c $'\trefs/tags/'"$TAG"'\^{}$' || true)
              PEELED_SHA=$(printf '%s\n' "$REMOTE_TAGS" | awk -v ref="refs/tags/$TAG^{}" '$2 == ref { print $1 }')
              test "$DIRECT_COUNT" = "1" && test "$PEELED_COUNT" = "1" && test "$PEELED_SHA" = "$EXPECTED_SHA" || {
                echo "tag must be uniquely annotated at expected_sha: $TAG" >&2
                exit 1
              }
            done < "$RECORDS"
          }
          verify_tags collect

          TAG_REFS=()
          while IFS= read -r TAG; do
            [ -n "$TAG" ] || continue
            ! git show-ref --verify --quiet "refs/tags/$TAG" || { echo "conflicting local tag $TAG" >&2; exit 1; }
            git tag -a "$TAG" "$EXPECTED_SHA" -m "$TAG"
            TAG_REFS+=("refs/tags/$TAG:refs/tags/$TAG")
          done < /tmp/missing-tags
          if [ "${#TAG_REFS[@]}" -gt 0 ]; then
            git push --atomic origin "${TAG_REFS[@]}"
          fi
          verify_tags verify

          verify_releases() {
            MODE=$1
            [ "$MODE" != "collect" ] || : > /tmp/missing-releases
            while IFS=$'\t' read -r PROJECT MANIFEST NAME VERSION TAG; do
              set +e
              RELEASE_JSON=$(gh release view "$TAG" --json tagName,isDraft,isPrerelease 2>/tmp/gh-release-error)
              STATUS=$?
              set -e
              if [ "$STATUS" = "0" ]; then
                printf '%s' "$RELEASE_JSON" | jq -e --arg tag "$TAG" '.tagName == $tag and .isDraft == false and .isPrerelease == true' >/dev/null || {
                  echo "conflicting GitHub Release for $TAG" >&2
                  exit 1
                }
              elif [ "$STATUS" = "1" ] && grep -Fqi "release not found" /tmp/gh-release-error; then
                [ "$MODE" = "collect" ] || { echo "missing GitHub prerelease $TAG" >&2; exit 1; }
                printf '%s\n' "$TAG" >> /tmp/missing-releases
              else
                echo "unknown GitHub Release state for $TAG" >&2
                exit 1
              fi
            done < "$RECORDS"
          }
          verify_releases collect
          while IFS= read -r TAG; do
            [ -n "$TAG" ] || continue
            gh release create "$TAG" --verify-tag --prerelease --generate-notes
          done < /tmp/missing-releases
          verify_releases verify

          MISSING_PROJECTS=$(paste -sd, /tmp/missing-projects)
          if [ -n "$MISSING_PROJECTS" ]; then
            PROJECTS="$MISSING_PROJECTS"
            pnpm nx release publish "--projects=$PROJECTS" --tag=beta
          fi

          echo "post-verify npm beta state"
          while IFS=$'\t' read -r PROJECT MANIFEST NAME VERSION TAG; do
            VERSIONS_JSON=$(npm view "$NAME" versions --json) || { echo "unknown post-publish npm history for $NAME" >&2; exit 1; }
            printf '%s' "$VERSIONS_JSON" | jq -e --arg version "$VERSION" 'if type == "array" then index($version) != null else . == $version end' >/dev/null
            BETA_TAG=$(npm view "$NAME" dist-tags.beta --json | jq -er --arg version "$VERSION" 'select(. == $version)') || {
              echo "npm beta tag did not converge for $NAME" >&2
              exit 1
            }
          done < "$RECORDS"

      - name: 📊 Release summary
        if: always()
        env:
          MODE: ${{ steps.release.outputs.mode || 'failed' }}
          HAS_PROJECTS: ${{ steps.release.outputs.has_projects || 'false' }}
          PROJECTS: ${{ steps.release.outputs.projects || '' }}
          SOURCE_SHA: ${{ steps.prepare.outputs.source_sha || '' }}
          SOURCE_REF: ${{ steps.prepare.outputs.source_ref || '' }}
          RELEASE_BRANCH: ${{ steps.prepare.outputs.branch || '' }}
          SELECTED_VERSIONS: ${{ steps.prepare.outputs.versions || '' }}
          CHANGED_PATHS: ${{ steps.prepare.outputs.changed_paths || '' }}
          EXPECTED_SHA: ${{ inputs.expected_sha || '' }}
        run: |
          echo "## 🚀 Beta Release Summary" >> "$GITHUB_STEP_SUMMARY"
          echo "**Mode:** $MODE" >> "$GITHUB_STEP_SUMMARY"
          echo "**Projects:** ${PROJECTS:-none}" >> "$GITHUB_STEP_SUMMARY"
          if [ "$MODE" = "prepare" ] && [ "$HAS_PROJECTS" = "true" ]; then
            echo "**Source:** $SOURCE_SHA ($SOURCE_REF)" >> "$GITHUB_STEP_SUMMARY"
            echo "**Prepared branch:** $RELEASE_BRANCH" >> "$GITHUB_STEP_SUMMARY"
            echo "**Selected versions:** $SELECTED_VERSIONS" >> "$GITHUB_STEP_SUMMARY"
            echo "**Changed paths:** $CHANGED_PATHS" >> "$GITHUB_STEP_SUMMARY"
            echo 'Create or reuse an approved issue, then manually open one linked PR to protected master; its sole `type:*` label is `type:chore`.' >> "$GITHUB_STEP_SUMMARY"
          elif [ "$MODE" = "suppress" ]; then
            echo "Structurally exact beta release output detected; preparation and publication were suppressed." >> "$GITHUB_STEP_SUMMARY"
          elif [ "$MODE" = "finalize" ]; then
            echo "**Expected master SHA:** $EXPECTED_SHA" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "No selected release projects or mode resolution failed." >> "$GITHUB_STEP_SUMMARY"
          fi