fleet-e2e.yaml

# Fleet E2E - revalidates the downstream cascade-example fleet on live GitHub.
#
# This is maintainer CI: hand-written tooling that lives in cascade's repo, not
# a product feature and not part of cascade's generated output. A green Fleet
# run means: this cascade version validated across all example repos, each
# running its own scenario-suite.yaml in its OWN repo context (own token, own
# main, own manifest). It is the release-candidate fleet gate.
#
# Fan-out shape: every example repo dispatches its suite under one shared fleet
# token. Bursting all of them at once tripped transient GitHub API 401/403/500
# on a rotating repo each run, so the lanes are serialized to hold peak live
# concurrency near two repos. A gh() transient-retry wrapper inside each suite
# remains the per-call backstop; this file only fixes the structural burst.
#
# Triggers:
#   workflow_run  of "Release" on completion - the fleet validates the PUBLISHED
#                 artifact. Release runs GoReleaser on every rc tag push, so a
#                 successful Release run means the binary the suites install is
#                 actually on the releases page. Fleet only fans out once that
#                 publish succeeded for an rc tag. No runner held open polling.
#   workflow_dispatch  manual override (bypasses the rc-tag gate intentionally),
#                 with an optional cascade_version input and an optional repos
#                 selector to run a subset of lanes.
#
# We key off "Release" rather than the `release:` event because promote-driven
# API releases do not reliably emit `release: published` (see release.yaml #86);
# the rc-tag push that drives GoReleaser is the dependable signal.
#
# IMPORTANT: the workflow_run trigger references the source workflow by its
# `name:` ("Release"). Keep that name in sync with release.yaml.
name: Fleet E2E (live GitHub)

on:
  workflow_run:
    workflows: ["Release"]
    types: [completed]
    # Only fan out for a release-candidate or rehearsal tag. When a green fleet
    # auto-promotes, it dispatches Release again for the final vX.Y.Z tag to
    # build the published assets; that second Release run must not re-enter the
    # fleet, or it triggers a redundant no-op fleet plus auto-promote lap. The
    # head_branch of a Release run dispatched by ref is the tag short-name, so
    # these globs match the rc and dryrun tags and skip the final release tag.
    # The resolve/plan jobs keep an equivalent rc-candidate guard as a backstop.
    branches:
      - "*-rc.*"
      - "*-dryrun.*"
  workflow_dispatch:
    inputs:
      cascade_version:
        description: >-
          cascade version to validate (e.g. v1.2.0-rc.1). Default empty resolves
          to the rc tag on the workflow_run path. resolve peels this to its
          commit sha, then the repin job re-stamps every example repo's
          committed workflows onto it before any suite lane fans out.
        required: false
        default: ''
      repos:
        description: >-
          Which example repos to run. Default `all` runs the whole fleet. Pass a
          comma or space separated subset of repo short names (e.g. `4env` or
          `2env,callbacks`) to run only those lanes; the rest are skipped and the
          Fleet gate aggregates over just the selected lanes. Intended as a
          maintainer debug override, not a release path.
        required: false
        default: 'all'

permissions:
  contents: read

# Single in-flight fleet run per rc tag; a newer rc supersedes an older queued
# fleet run rather than piling up live cross-repo dispatches.
concurrency:
  group: fleet-e2e-${{ github.event.workflow_run.head_branch || github.event.inputs.cascade_version || github.run_id }}
  cancel-in-progress: false

env:
  FLEET_OWNER: stablekernel

jobs:
  # Resolve the cascade version under test and re-assert the rc-tag gate as a
  # job output so every fan-out job can gate on it cheaply. Also depends on
  # plan so it can carry the full_run status (true only for repos=all/default)
  # across the workflow_run boundary to auto-promote, which gates on it.
  resolve:
    name: Resolve version under test
    needs: plan
    runs-on: ubuntu-latest
    # Top-level guard: only fan out for a manual dispatch, or a green
    # Release run for a candidate tag. This filters out non-candidate tag
    # publishes and any non-success completions.
    #
    # A candidate is an rc tag (vX.Y.Z-rc.N) or a dry-run tag
    # (vX.Y.Z-dryrun.N). Accepting -dryrun. lets a nightly dry run fan out
    # across the full staged fleet exactly like a real rc; auto-promote's
    # unchanged -rc.-only gate still keeps a dry run from ever publishing.
    #
    # We accept the source Release whether it was started by a tag push OR by an
    # explicit workflow_dispatch against the tag. The tag-push trigger is
    # unreliable when the candidate tag points at a state commit whose message
    # suppresses CI, so orchestrate dispatches Release explicitly against the
    # tag; that path arrives here as event == 'workflow_dispatch' and must fan
    # the fleet out exactly like the push path. A Release dispatched against a
    # non-candidate ref (e.g. the final vX.Y.Z tag auto-promote publishes, or
    # main) still fails the head_branch candidate check below and does not fan out.
    #
    # workflow_run.head_branch carries the short ref name of whatever triggered
    # the source run. For a tag push or a tag-ref dispatch that is the tag's
    # short name (e.g. v1.2.0-rc.1). We gate on it here AND, in the compute step
    # below, resolve the tag from head_sha as a fallback in case head_branch is
    # ever empty for a tag-triggered source run.
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event.workflow_run.conclusion == 'success' &&
       (github.event.workflow_run.event == 'push' ||
        github.event.workflow_run.event == 'workflow_dispatch') &&
       startsWith(github.event.workflow_run.head_branch, 'v') &&
       (contains(github.event.workflow_run.head_branch, '-rc.') ||
        contains(github.event.workflow_run.head_branch, '-dryrun.')))
    permissions:
      contents: read
      actions: read
    outputs:
      cascade_version: ${{ steps.compute.outputs.cascade_version }}
      cascade_version_sha: ${{ steps.compute.outputs.cascade_version_sha }}
    steps:
      - name: Compute cascade version under test
        id: compute
        env:
          # PAT is only needed for the head_sha -> tag fallback (a cross-ref
          # lookup against this repo's tags). GITHUB_TOKEN would also work for
          # same-repo reads, but we standardise on the fleet PAT.
          GH_TOKEN: ${{ secrets.CASCADE_STATE_TOKEN }}
          EVENT_NAME: ${{ github.event_name }}
          INPUT_VERSION: ${{ github.event.inputs.cascade_version }}
          WR_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          WR_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
        run: |
          set -euo pipefail
          if [ "$EVENT_NAME" = "workflow_dispatch" ] && [ -n "$INPUT_VERSION" ]; then
            VERSION="$INPUT_VERSION"
          elif [ -n "$WR_HEAD_BRANCH" ]; then
            # Primary path: the rc tag short-name from the source push run.
            VERSION="$WR_HEAD_BRANCH"
          elif [ -n "$WR_HEAD_SHA" ]; then
            # Fallback: head_branch was empty; resolve the candidate tag pointing
            # at the source run's head_sha. Tolerated to be empty (dispatch with
            # no input), so guard the lookup.
            # A sha can carry more than one candidate tag; pick the highest by
            # version sort so selection is deterministic regardless of API
            # ordering. Accept rc and dryrun tags (see the resolve gate).
            VERSION=$(gh api "repos/${GITHUB_REPOSITORY}/tags" \
              --jq ".[] | select(.commit.sha == \"$WR_HEAD_SHA\") | .name" \
              | grep -E -- '-(rc|dryrun)\.' | sort -V -r | head -n 1 || true)
          else
            VERSION=""
          fi

          echo "cascade_version=$VERSION" >> "$GITHUB_OUTPUT"

          # Peel the resolved rc tag to its underlying commit sha centrally so
          # each suite can SHA-pin its setup-cli self-action (cli_version_sha) to
          # the exact commit. cascade's release tags are annotated, so
          # refs/tags/<rc> is a tag-object sha; ^{} dereferences to the commit.
          # A lightweight tag has no peeled ref, so fall back to the bare ref,
          # which is already the commit. An empty VERSION (a dispatch with no
          # input) stays a clean no-op: no tag, no sha.
          VERSION_SHA=""
          if [ -n "$VERSION" ]; then
            VERSION_SHA=$(git ls-remote "https://github.com/${GITHUB_REPOSITORY}" "refs/tags/${VERSION}^{}" | awk '{print $1}')
            if [ -z "$VERSION_SHA" ]; then
              VERSION_SHA=$(git ls-remote "https://github.com/${GITHUB_REPOSITORY}" "refs/tags/${VERSION}" | awk '{print $1}')
            fi
            if ! printf '%s' "$VERSION_SHA" | grep -qE '^[0-9a-f]{40}$'; then
              echo "::error::Could not resolve a commit sha for tag ${VERSION} (got '${VERSION_SHA}')"
              exit 1
            fi
            echo "Resolved ${VERSION} to commit ${VERSION_SHA}"
          fi
          echo "cascade_version_sha=$VERSION_SHA" >> "$GITHUB_OUTPUT"
          # Persist the resolved version so it can cross the workflow_run
          # boundary into auto-promote. This is the exact value every suite is
          # pinned to, so a green fleet and the promoted base never disagree.
          printf '%s' "$VERSION" > version-under-test.txt
          {
            echo "## Fleet E2E"
            echo ""
            echo "Trigger: \`$EVENT_NAME\`"
            echo "cascade version under test: \`${VERSION:-<empty>}\`"
            echo ""
            echo "> The repin job re-stamps every example repo's committed"
            echo "> workflows onto this version before any suite lane fans out,"
            echo "> so each suite runs the binary named here from a fresh pin"
            echo "> rather than a stale committed one."
          } >> "$GITHUB_STEP_SUMMARY"

      # Write the full_run marker (true only when repos=all/default). Auto-promote
      # uses this to refuse promotion from selective/partial fleet runs; only a
      # full validation is a safe release signal.
      - name: Write fleet validation completeness marker
        env:
          FULL_RUN: ${{ needs.plan.outputs.full_run }}
        run: |
          printf '%s' "$FULL_RUN" > full-run.txt

      # Hand the resolved version-under-test and run completeness to auto-promote.
      # A workflow_run does not inherit the triggering run's dispatch inputs, so
      # auto-promote reads these artifacts as the authoritative version and
      # validation scope the fleet checked, rather than guessing from head_branch
      # (which is `main` on the workflow_dispatch path).
      - name: Upload resolved version-under-test and run status
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: version-under-test
          path: |
            version-under-test.txt
            full-run.txt
          if-no-files-found: error
          retention-days: 7

  # Plan which lanes run. Parses the `repos` selector once and emits the lane
  # gates and matrices every fan-out job keys off. This is the ONE obvious place
  # the fleet roster lives: to add a repo (e.g. cascade-example-rollback-dispatch)
  # add its short name to the matching list below and it joins that lane.
  plan:
    name: Plan selected lanes
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      run_primary: ${{ steps.select.outputs.run_primary }}
      run_dependents: ${{ steps.select.outputs.run_dependents }}
      run_heavy: ${{ steps.select.outputs.run_heavy }}
      run_remainder: ${{ steps.select.outputs.run_remainder }}
      dependents_repos: ${{ steps.select.outputs.dependents_repos }}
      remainder_repos: ${{ steps.select.outputs.remainder_repos }}
      full_run: ${{ steps.select.outputs.full_run }}
    steps:
      - name: Select lanes from repos input
        id: select
        env:
          # Default `all` on the workflow_run path, where there is no input.
          REPOS_INPUT: ${{ github.event.inputs.repos }}
        run: |
          set -euo pipefail

          # ---- Canonical fleet roster (single source of truth) --------------
          # PRIMARY runs first; DEPENDENTS mutate primary's shared external
          # state so they follow it. HEAVY is the heaviest, most fragile repo
          # and runs alone. REMAINDER is every other light repo, capped at two
          # in flight. Add a new repo to the list for the lane it belongs to.
          PRIMARY_REPO="primary"
          DEPENDENTS="artifact-a artifact-b"
          HEAVY_REPO="4env"
          REMAINDER="3env 2env single-env release-only no-env callbacks rollback-dispatch monorepo"
          # -------------------------------------------------------------------

          RAW="${REPOS_INPUT:-all}"
          # Normalise commas to spaces and collapse whitespace.
          SEL=$(printf '%s' "$RAW" | tr ',' ' ' | tr -s '[:space:]' ' ' \
            | sed -E 's/^ //; s/ $//')
          ALL=0
          if [ -z "$SEL" ] || [ "$SEL" = "all" ]; then
            ALL=1
          fi

          # want <name>: is this repo selected?
          want() {
            [ "$ALL" -eq 1 ] && return 0
            local c="$1" s
            for s in $SEL; do
              [ "$c" = "$s" ] && return 0
            done
            return 1
          }

          # json_array <candidates>: emit a JSON string array of the selected
          # repos for use as a matrix dimension value (matrix.repo iterates the
          # strings). Empty when none selected; the lane gate skips it then.
          json_array() {
            local cands="$1" first=1 out="[" c
            for c in $cands; do
              if want "$c"; then
                if [ "$first" -eq 1 ]; then first=0; else out="$out,"; fi
                out="$out\"$c\""
              fi
            done
            printf '%s]' "$out"
          }

          # any <candidates>: true if at least one is selected.
          any() {
            local c
            for c in $1; do
              want "$c" && { echo "true"; return; }
            done
            echo "false"
          }

          RUN_PRIMARY=$(want "$PRIMARY_REPO" && echo true || echo false)
          RUN_HEAVY=$(want "$HEAVY_REPO" && echo true || echo false)
          RUN_DEPENDENTS=$(any "$DEPENDENTS")
          RUN_REMAINDER=$(any "$REMAINDER")
          DEPENDENTS_JSON=$(json_array "$DEPENDENTS")
          REMAINDER_JSON=$(json_array "$REMAINDER")
          # full_run is true only when repos input is `all` (or empty/default).
          # Auto-promote gates on this: a selective fleet run (any subset) never
          # promotes, even if it passes, because only a full fleet validation is
          # a safe release signal.
          FULL_RUN=$([ "$ALL" -eq 1 ] && echo true || echo false)

          {
            echo "run_primary=$RUN_PRIMARY"
            echo "run_dependents=$RUN_DEPENDENTS"
            echo "run_heavy=$RUN_HEAVY"
            echo "run_remainder=$RUN_REMAINDER"
            echo "dependents_repos=$DEPENDENTS_JSON"
            echo "remainder_repos=$REMAINDER_JSON"
            echo "full_run=$FULL_RUN"
          } >> "$GITHUB_OUTPUT"

          {
            echo "## Fleet lane selection"
            echo ""
            echo "repos input: \`${RAW}\`"
            echo ""
            echo "| Lane | Will run |"
            echo "|---|---|"
            echo "| primary | $RUN_PRIMARY |"
            echo "| dependents | $RUN_DEPENDENTS |"
            echo "| 4env (heavy) | $RUN_HEAVY |"
            echo "| remainder | $RUN_REMAINDER |"
          } >> "$GITHUB_STEP_SUMMARY"

  # Repin: re-stamp every example repo's committed workflows onto the rc under
  # test BEFORE any suite lane fans out. A suite cannot repin its own committed
  # setup-cli `uses:` ref, because GitHub resolves a job's `uses:` refs from the
  # workflow file as it existed at trigger time, before any in-job step runs. So
  # a stale or pruned committed ref would kill the lane at "Set up job" before an
  # in-suite repin could fire. This job clones each repo fresh, regenerates its
  # workflows against the rc binary, and pushes to main; every suite lane gates
  # on it so none starts against a stale committed ref. Delegated to the reusable
  # suite-rc-repin.yaml so the logic lives in one place.
  repin:
    name: Repin fleet to rc
    needs: [resolve, plan]
    uses: ./.github/workflows/suite-rc-repin.yaml
    with:
      cascade_version: ${{ needs.resolve.outputs.cascade_version }}
      cascade_version_sha: ${{ needs.resolve.outputs.cascade_version_sha }}
    secrets: inherit

  # Lane 1, stage 1: primary must run and pass before its dependents. Gated on
  # the plan selector and on a green repin, so it never runs against a stale
  # committed ref.
  primary:
    name: primary
    needs: [resolve, plan, repin]
    if: needs.plan.outputs.run_primary == 'true' && needs.repin.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Dispatch and watch primary
        uses: ./.github/actions/dispatch-suite
        with:
          repo: ${{ env.FLEET_OWNER }}/cascade-example-primary
          token: ${{ secrets.CASCADE_STATE_TOKEN }}
          cascade_version: ${{ needs.resolve.outputs.cascade_version }}
          cascade_version_sha: ${{ needs.resolve.outputs.cascade_version_sha }}
          # Allow one whole-suite re-dispatch so a transient runner
          # non-acquisition, a mid-poll API blip, or a SIGPIPE does not red the
          # lane on a single unlucky attempt. Safe because each scenario-suite
          # run self-resets on its first step, so a re-dispatch starts clean.
          retry-attempts: '2'

  # Lane 1, stage 2: dependents of primary (mutate primary's shared external
  # state), so they only start after primary is green. Two repos run together,
  # which is the lane that defines the fleet's ~2 peak. dependents require a
  # green primary in the same pass; selecting a dependent without primary skips
  # it (primary sets up the state they mutate).
  dependents:
    name: dependents (${{ matrix.repo }})
    needs: [resolve, plan, repin, primary]
    if: needs.plan.outputs.run_dependents == 'true' && needs.primary.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    strategy:
      fail-fast: false
      matrix:
        repo: ${{ fromJSON(needs.plan.outputs.dependents_repos) }}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Dispatch and watch
        uses: ./.github/actions/dispatch-suite
        with:
          repo: ${{ env.FLEET_OWNER }}/cascade-example-${{ matrix.repo }}
          token: ${{ secrets.CASCADE_STATE_TOKEN }}
          cascade_version: ${{ needs.resolve.outputs.cascade_version }}
          cascade_version_sha: ${{ needs.resolve.outputs.cascade_version_sha }}
          # Allow one whole-suite re-dispatch so a transient runner
          # non-acquisition, a mid-poll API blip, or a SIGPIPE does not red the
          # lane on a single unlucky attempt. Safe because each scenario-suite
          # run self-resets on its first step, so a re-dispatch starts clean.
          retry-attempts: '2'

  # Lane 2: 4env alone. It is the heaviest and most fragile repo, so it runs in
  # its own dedicated job with nothing beside it. Sequenced AFTER the dependents
  # lane (via needs) so the two-repo dependents peak and this lane never stack;
  # `always()` lets it proceed when the primary/dependents lane was filtered out
  # by the selector. Still gated on a green repin so it never runs against a
  # stale committed ref.
  heavy:
    name: 4env (heavy)
    needs: [resolve, plan, repin, dependents]
    if: always() && needs.plan.outputs.run_heavy == 'true' && needs.repin.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Dispatch and watch 4env
        uses: ./.github/actions/dispatch-suite
        with:
          repo: ${{ env.FLEET_OWNER }}/cascade-example-4env
          token: ${{ secrets.CASCADE_STATE_TOKEN }}
          cascade_version: ${{ needs.resolve.outputs.cascade_version }}
          cascade_version_sha: ${{ needs.resolve.outputs.cascade_version_sha }}
          # The heavy lane is the single most race-prone surface (full lifecycle
          # plus chained multi-env hotfix, conflict, rollback, and merge_queue
          # against one live repo). Allow one whole-suite re-dispatch so a live
          # GitHub eventual-consistency blip does not red the lane. Safe because
          # each suite run self-resets on its first step. Every fan-out lane
          # carries the same single re-dispatch so a transient failure on any of
          # them re-dispatches once rather than redding the whole fleet.
          retry-attempts: '2'

  # Lane 3: the light remainder, run one repo at a time. Sequenced AFTER
  # the heavy lane (via needs) so 4env and this matrix never overlap;
  # `always()` lets it proceed when the heavy lane was filtered out. Still
  # gated on a green repin. max-parallel is serialized (was 2) to lower the
  # fleet's peak hosted-runner demand: each suite dispatches several of its
  # own child runs, so two suites in flight at once was enough concurrent
  # runner requests that GitHub occasionally could not acquire a hosted
  # runner in time and cancelled the lane. Running the remainder repos one at
  # a time trades a longer remainder lane for far fewer runner-starvation
  # flakes, without touching the already-serial primary/dependents/heavy
  # sequencing ahead of it.
  remainder:
    name: remainder (${{ matrix.repo }})
    needs: [resolve, plan, repin, heavy]
    if: always() && needs.plan.outputs.run_remainder == 'true' && needs.repin.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        repo: ${{ fromJSON(needs.plan.outputs.remainder_repos) }}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: Dispatch and watch
        uses: ./.github/actions/dispatch-suite
        with:
          repo: ${{ env.FLEET_OWNER }}/cascade-example-${{ matrix.repo }}
          token: ${{ secrets.CASCADE_STATE_TOKEN }}
          cascade_version: ${{ needs.resolve.outputs.cascade_version }}
          cascade_version_sha: ${{ needs.resolve.outputs.cascade_version_sha }}
          # Allow one whole-suite re-dispatch so a transient runner
          # non-acquisition, a mid-poll API blip, or a SIGPIPE does not red the
          # lane on a single unlucky attempt. Safe because each scenario-suite
          # run self-resets on its first step, so a re-dispatch starts clean.
          retry-attempts: '2'

  # Fan-in: this job's conclusion is the rc fleet gate. It needs EVERY lane so a
  # green gate means every selected repo passed; auto-promote keys off this
  # conclusion. A lane that the repos selector skipped reports `skipped` and is
  # treated as satisfied, so a subset run still produces a meaningful verdict
  # over exactly the lanes that ran. A real fan-out failure still reds the run.
  aggregate:
    name: Fleet gate
    needs: [resolve, plan, repin, primary, dependents, heavy, remainder]
    # Always run so the gate renders a verdict rather than inheriting a skip.
    # A skipped aggregate reads as success (skipped != failed), so if this job
    # were gated on resolve succeeding, a fleet that resolved no rc and ran no
    # lanes would conclude green having validated nothing (a false green). The
    # step below fails closed instead: in a context that was OBLIGATED to
    # validate a candidate, it requires a resolved rc and at least one lane run
    # to a real conclusion, else it reds. A context with nothing to validate
    # (e.g. a non-candidate Release completion) stays a clean green no-op.
    if: always()
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Aggregate fleet result
        env:
          EVENT_NAME: ${{ github.event_name }}
          WR_EVENT: ${{ github.event.workflow_run.event }}
          WR_CONCLUSION: ${{ github.event.workflow_run.conclusion }}
          WR_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          R_RESOLVE: ${{ needs.resolve.result }}
          R_REPIN: ${{ needs.repin.result }}
          R_PRIMARY: ${{ needs.primary.result }}
          R_DEPENDENTS: ${{ needs.dependents.result }}
          R_HEAVY: ${{ needs.heavy.result }}
          R_REMAINDER: ${{ needs.remainder.result }}
          VERSION: ${{ needs.resolve.outputs.cascade_version }}
        run: |
          set -euo pipefail
          {
            echo "## Fleet E2E result"
            echo ""
            echo "cascade version under test (pinned into every suite): \`${VERSION:-<empty>}\`"
            echo ""
            echo "| Lane | Result |"
            echo "|---|---|"
            echo "| resolve (version under test) | $R_RESOLVE |"
            echo "| repin (all example repos to rc) | $R_REPIN |"
            echo "| primary | $R_PRIMARY |"
            echo "| dependents (artifact-a, artifact-b) | $R_DEPENDENTS |"
            echo "| 4env (heavy, alone) | $R_HEAVY |"
            echo "| remainder (3env, 2env, single-env, release-only, no-env, callbacks, rollback-dispatch, monorepo) | $R_REMAINDER |"
            echo ""
            echo "> rc gate: this conclusion is the fleet validation signal for"
            echo "> the rc tag. The repin job re-stamped every example repo onto"
            echo "> this rc before fan-out, so a green gate validates the binary"
            echo "> named above."
            echo "> A lane shown as 'skipped' was not selected by the repos input."
            echo "> rc -> release promotion should consume the latest fleet-e2e"
            echo "> conclusion for that tag before promoting, and only from a"
            echo "> full (repos=all) run."
          } >> "$GITHUB_STEP_SUMMARY"

          # Was this run obligated to validate a candidate? Mirror the resolve
          # job's own gate: a manual fleet dispatch, or a green Release (push or
          # explicit dispatch) for an rc/dryrun tag. Anything else genuinely has
          # nothing to validate and is a clean green no-op.
          should_validate=0
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            should_validate=1
          elif [ "$WR_CONCLUSION" = "success" ] &&
               { [ "$WR_EVENT" = "push" ] || [ "$WR_EVENT" = "workflow_dispatch" ]; } &&
               case "$WR_HEAD_BRANCH" in v*) true ;; *) false ;; esac &&
               case "$WR_HEAD_BRANCH" in *-rc.*|*-dryrun.*) true ;; *) false ;; esac; then
            should_validate=1
          fi

          if [ "$should_validate" -ne 1 ]; then
            echo "Not an rc validation context (event=$EVENT_NAME, source=$WR_EVENT, ref=${WR_HEAD_BRANCH:-<none>}); nothing to validate."
            exit 0
          fi

          # Fail closed on a no-op in a context that SHOULD have validated. A
          # resolve that did not succeed, an empty version under test, or zero
          # lanes run means the fleet validated nothing and must never read as a
          # green release signal. This mirrors the reconcile require-ledger guard.
          if [ "$R_RESOLVE" != "success" ]; then
            echo "::error::Fleet E2E validated nothing: resolve did not succeed (result=$R_RESOLVE) in a candidate context. Failing closed."
            exit 1
          fi
          case "$VERSION" in
            v*-rc.*|v*-dryrun.*) : ;;
            *)
              echo "::error::Fleet E2E validated nothing: no candidate version under test (got '${VERSION:-<empty>}'). Failing closed."
              exit 1
              ;;
          esac

          # The repin job re-stamps every example repo onto the rc before any
          # lane fans out. It is never selector-gated, so in a validation context
          # it must have succeeded; a skipped or failed repin means the lanes ran
          # (or were prevented from running) against an unknown pin state and the
          # gate must red rather than read as a green release signal.
          if [ "$R_REPIN" != "success" ]; then
            echo "::error::Fleet E2E validated nothing: repin did not succeed (result=$R_REPIN) in a candidate context. Failing closed."
            exit 1
          fi

          # A validation lane passes when it succeeded OR was skipped (filtered
          # out by the repos selector, or - for dependents - skipped because
          # primary was not selected). Only an actual failure or cancellation
          # reds the gate.
          fail=0
          for r in "$R_PRIMARY" "$R_DEPENDENTS" "$R_HEAVY" "$R_REMAINDER"; do
            if [ "$r" != "success" ] && [ "$r" != "skipped" ]; then
              fail=1
            fi
          done
          if [ "$fail" -ne 0 ]; then
            echo "::error::Fleet E2E failed: one or more lanes did not pass"
            exit 1
          fi

          # Positive assertion: at least one validation lane must have actually
          # run to success. If every fan-out lane was skipped, the fleet
          # exercised no example repo and cannot count as a green validation of
          # the candidate.
          ran=0
          for r in "$R_PRIMARY" "$R_DEPENDENTS" "$R_HEAVY" "$R_REMAINDER"; do
            if [ "$r" = "success" ]; then
              ran=1
            fi
          done
          if [ "$ran" -ne 1 ]; then
            echo "::error::Fleet E2E validated nothing: no fan-out lane ran to success. Failing closed."
            exit 1
          fi

          echo "Fleet E2E passed across all selected lanes"