release.yml

# Release pipeline: lint → test → build → smoke/soak → draft → verify → publish
#
# Security (security-static + license-gate) and CodeQL (codeql.yml: full scan
# of this commit + the open-alert check) start immediately and run in
# parallel with lint/test/build/smoke/soak. They only block the final verify
# step — everything else proceeds independently.
name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Release version (e.g. v0.8.0)"
        required: true
        type: string
      release_notes:
        description: "Release notes (optional — auto-generated from commits if empty)"
        required: false
        type: string
      soak_level:
        description: 'Soak: full (quick+asan) or quick (10min)'
        type: choice
        options: ['full', 'quick']
        default: 'quick'
      skip_perf:
        description: "Skip performance tests (use when no pipeline logic changed)"
        required: false
        type: boolean
        default: false
      skip_tests:
        description: "Skip tests only when the exact SHA has a successful Jenkins full-gate status; build/smoke/soak/verify still run"
        required: false
        type: boolean
        default: false
      hold_for_external_qualification:
        description: "Hold the verified GitHub release in draft for native-Windows external qualification before registry publication"
        required: false
        type: boolean
        default: true
      publish_registries:
        description: "Publish npm/PyPI packages and make the GitHub release public (requires registry credentials)"
        required: false
        type: boolean
        default: false
      platforms:
        description: "Target platforms: all (eight archives, default) or linux (linux-amd64, linux-arm64 and both portable archives only; GitHub prerelease route, no Windows/macOS bytes)"
        type: choice
        options: ['all', 'linux']
        default: 'all'
      publish_github_prerelease:
        description: "Make a verified prerelease public on GitHub only (no npm/PyPI). Requires a hyphenated version, hold_for_external_qualification=false and publish_registries=false"
        required: false
        type: boolean
        default: false

permissions:
  contents: read

jobs:
  # ── Security (starts immediately, blocks only verify) ───────────
  security:
    uses: ./.github/workflows/_security.yml
    permissions:
      contents: read
      security-events: read
      actions: read
    secrets: inherit

  # ── CodeQL (starts immediately, blocks only verify) ──────────────
  # Full scan of this exact commit (every language, vendored C included) +
  # the open-alert check. codeql.yml uploads results and reads the alerts:
  # a called workflow cannot request more than its caller grants, so
  # withholding either permission fails the whole run at startup.
  codeql:
    uses: ./.github/workflows/codeql.yml
    permissions:
      contents: read
      security-events: write
      actions: read

  # ── 0. Preflight: refuse malformed dispatch inputs ──────────────
  # The tag is inputs.version VERBATIM. A bare "0.10.7" publishes a release the
  # installers can never resolve (they fetch releases/download/v<version>/...),
  # and with immutable releases the mis-named tag cannot be retagged, deleted,
  # or its name reused — the name is burned permanently (2026-08-18 incident).
  preflight:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Enforce v-prefixed semver version input
        env:
          VERSION: ${{ inputs.version }}
        run: |
          if [[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
            echo "version OK: $VERSION"
          else
            echo "::error::version must be v-prefixed semver (vX.Y.Z), got '$VERSION'"
            exit 1
          fi

      # Reject input combinations that would publish bytes the gates never
      # covered or skip a qualification the dispatch asked for.
      - name: Reject invalid input combinations
        env:
          VERSION: ${{ inputs.version }}
          PLATFORMS: ${{ inputs.platforms }}
          HOLD: ${{ inputs.hold_for_external_qualification }}
          REGISTRIES: ${{ inputs.publish_registries }}
          PRERELEASE_PUBLISH: ${{ inputs.publish_github_prerelease }}
        run: bash scripts/ci/validate-release-inputs.sh

      - name: Require exact-SHA Jenkins evidence when skipping tests
        if: ${{ inputs.skip_tests }}
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPOSITORY: ${{ github.repository }}
          REVISION: ${{ github.sha }}
        run: |
          if ! gh api "repos/$REPOSITORY/commits/$REVISION/statuses" \
              --jq '.[] | select(.context == "jenkins/codebase-memory-cli-main/full-gate" and .state == "success")' \
              | grep -q .; then
            echo "::error::skip_tests requires a successful Jenkins full-gate status for exact SHA $REVISION"
            exit 1
          fi
          echo "Jenkins full-gate evidence accepted for $REVISION"

  # ── 1. Lint (cppcheck + clang-format) ───────────────────────────
  lint:
    needs: [preflight]
    uses: ./.github/workflows/_lint.yml

  # ── 2. Tests (all platforms, full suite for release) ────────────
  # skip_tests exists for RE-releases of a tree whose tests are already green:
  # when only packaging/gating changed and the previous run proved the suites,
  # re-running ~2h of tests adds no information. It skips ONLY this phase —
  # build, smoke, soak and verify always run against the fresh artifacts.
  test:
    if: ${{ !inputs.skip_tests }}
    needs: [lint]
    uses: ./.github/workflows/_test.yml
    with:
      skip_perf: ${{ inputs.skip_perf }}
      broad_platforms: true
      platforms: ${{ inputs.platforms }}
      shard_suites: true

  # ── 3. Build all platforms ──────────────────────────────────────
  # `test` may be skipped ONLY by the skip_tests input. A skipped `test` is
  # also what a cancelled/timed-out lint produces (needs-cascade), and the
  # bare !cancelled() && !failure() form cannot tell those apart: failure()
  # does not cover a needed job that was CANCELLED, so a lint timeout let the
  # whole pipeline publish with the test matrix silently skipped
  # (v0.10.7 incident, 2026-08-18). Require the explicit results.
  build:
    if: >-
      ${{ !cancelled()
      && needs.lint.result == 'success'
      && (needs.test.result == 'success'
          || (inputs.skip_tests && needs.test.result == 'skipped')) }}
    needs: [lint, test]
    permissions:
      contents: read
      id-token: write
      attestations: write
    uses: ./.github/workflows/_build.yml
    with:
      version: ${{ inputs.version }}
      attest: true
      # Release builds have no scan bypass: both candidates in all eight
      # immutable target tuples must complete before smoke or soak starts.
      scan_candidates: true
      platforms: ${{ inputs.platforms }}
    secrets: inherit

  # ── 4. Smoke test every binary ──────────────────────────────────
  # !cancelled() && !failure(): GitHub propagates "skipped" TRANSITIVELY down the
  # needs graph, so with skip_tests=true a skipped `test` skipped smoke and soak
  # too — even though `build` overrode the same condition and succeeded. Nothing
  # failed and nothing said so; the pipeline simply carried on toward publishing
  # artifacts that had never been smoke-tested or soaked. Every job downstream of
  # an optional phase needs this override, or the phase being optional silently
  # makes the phases after it optional as well.
  smoke:
    if: ${{ !cancelled() && needs.build.result == 'success' }}
    needs: [build]
    uses: ./.github/workflows/_smoke.yml
    with:
      broad_platforms: true
      platforms: ${{ inputs.platforms }}

  # ── 5. Soak tests ──────────────────────────────────────────────
  soak:
    if: ${{ !cancelled() && needs.build.result == 'success' }}
    needs: [build]
    uses: ./.github/workflows/_soak.yml
    with:
      duration_minutes: 10
      run_asan: ${{ inputs.soak_level == 'full' }}
      version: ${{ inputs.version }}
      use_release_artifacts: true
      platforms: ${{ inputs.platforms }}

  # ── Waste sanitizer, REPORT-ONLY ────────────────────────────────
  # The same full run as the dry run, on the release commit. Not in
  # release-draft's needs: the report is evidence for the release notes, never
  # a publication gate.
  memwaste:
    uses: ./.github/workflows/_memwaste.yml
    with:
      mode: full

  # ── 6. Create DRAFT release ────────────────────────────────────
  # Requires smoke to have actually SUCCEEDED, not merely "not failed". The bare
  # !cancelled() && !failure() form is fail-OPEN: a skipped smoke is neither
  # cancelled nor failed, so a draft was one condition away from being cut from
  # binaries nobody had run. Selected release bytes must also finish soak; a
  # skipped soak is not an acceptable production-release state.
  release-draft:
    needs: [smoke, soak]
    if: >-
      ${{ !cancelled() && !failure()
      && needs.smoke.result == 'success'
      && needs.soak.result == 'success' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Download only selected release containers
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          pattern: binaries-*
          merge-multiple: true

      # Candidate artifacts are deliberately excluded from the container
      # download above. Preserve only the three reviewable manifests that bind
      # candidate bytes, VT results, and the tuple-local decision.
      - name: Download candidate selection evidence separately
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: release-selection-evidence
          path: selection-evidence

      - name: Verify and stage the exact evidence set
        run: |
          test "$(find selection-evidence -maxdepth 1 -type f | wc -l | tr -d ' ')" = 3
          for f in release-candidates.tsv virustotal-candidate-results.tsv release-selection.tsv; do
            test -f "selection-evidence/$f"
            cp "selection-evidence/$f" "$f"
          done

      - name: List selected artifacts and decision evidence
        # nullglob: a linux-only release has no *.zip.
        run: bash scripts/ci/release-artifacts.sh list

      - name: Generate checksums
        run: bash scripts/ci/release-artifacts.sh checksums

      - name: Attest checksum provenance
        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
        with:
          subject-path: checksums.txt

      # SBOM content lives in the canonical scripts/ci entry, not inline YAML
      # (venue-parity contract): vendored versions are reviewable there.
      - name: Generate SBOM
        run: python3 scripts/ci/generate-sbom.py "${{ inputs.version }}"

      # actions/attest-sbom is deprecated. What it does now is emit
      # "::warning::actions/attest-sbom has been deprecated" and forward to
      # actions/attest with NODE_OPTIONS set, passing sbom-path straight
      # through. Calling attest directly produces the same attestation without
      # the wrapper, and sbom-path is a first-class input there (verified
      # against the action definition at this exact SHA, which is tag v4.1.0).
      #
      # This step deliberately carries no continue-on-error: a release must
      # fail if its SBOM cannot be attested. An unattested SBOM is worse than
      # an absent one, because the artifact still ships looking complete.
      - name: Attest SBOM
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        env:
          NODE_OPTIONS: '--max-http-header-size=32768'
        with:
          subject-path: '*.tar.gz'
          sbom-path: 'sbom.json'

      - name: Install cosign
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Sign artifacts
        run: bash scripts/ci/release-artifacts.sh sign

      - name: Refuse an existing immutable release identity
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
        run: |
          if gh release view "$VERSION" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
            echo "::error::release $VERSION already exists; release identities are immutable"
            exit 1
          fi
          if git ls-remote --exit-code --tags origin "refs/tags/$VERSION" >/dev/null 2>&1; then
            echo "::error::tag $VERSION already exists; release identities are immutable"
            exit 1
          fi

      - name: Create immutable tag
        env:
          VERSION: ${{ inputs.version }}
        # Tag the DISPATCHED sha, not the checkout HEAD: the artifacts were
        # built from github.sha, and a commit pushed to main mid-run must not
        # move the release tag. A duplicate/racing push is expected to fail: a
        # release identity may never be deleted, force-moved, or reused.
        run: |
          git tag "$VERSION" "$GITHUB_SHA"
          git push origin "refs/tags/$VERSION"

      - uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
        with:
          tag_name: ${{ inputs.version }}
          draft: true
          # Semver prerelease (v0.9.1-rc.1): never the "latest" release on GitHub.
          prerelease: ${{ contains(inputs.version, '-') }}
          files: |
            *.tar.gz
            *.zip
            release-candidates.tsv
            virustotal-candidate-results.tsv
            release-selection.tsv
            checksums.txt
            sbom.json
            *.bundle
          body: ${{ inputs.release_notes || '' }}
          generate_release_notes: ${{ inputs.release_notes == '' }}

  # ── 7. Verify + Publish (requires the security and CodeQL gates) ─
  verify:
    needs: [release-draft, security, codeql]
    # Explicit condition: a deliberately skipped test ancestor must not skip
    # the publish chain; the draft itself proves smoke and soak both succeeded.
    if: ${{ !cancelled() && !failure() && needs.security.result == 'success' && needs.codeql.result == 'success' && needs.release-draft.result == 'success' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      # Canonical-order target set and the archive/binary/runtime-file counts
      # it implies (each archive: one executable plus three runtime sidecars).
      RELEASE_TARGETS: ${{ inputs.platforms == 'linux' && 'linux-amd64,linux-arm64,linux-amd64-portable,linux-arm64-portable' || 'linux-amd64,linux-arm64,linux-amd64-portable,linux-arm64-portable,darwin-amd64,darwin-arm64,windows-amd64,windows-arm64' }}
      EXPECT_ARCHIVES: ${{ inputs.platforms == 'linux' && '4' || '8' }}
      EXPECT_RUNTIME_FILES: ${{ inputs.platforms == 'linux' && '12' || '24' }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Download and extract release binaries
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
        run: |
          ARCHIVE_DIR="$RUNNER_TEMP/release-archives"
          mkdir -p "$ARCHIVE_DIR" binaries
          gh release download "$VERSION" --dir "$ARCHIVE_DIR" --repo "$GITHUB_REPOSITORY" --pattern '*.tar.gz' --pattern '*.zip'
          gh release download "$VERSION" --repo "$GITHUB_REPOSITORY" --pattern 'release-selection.tsv' --output "$RUNNER_TEMP/release-selection.tsv"
          python3 scripts/ci/verify-release-selection.py \
            --selection "$RUNNER_TEMP/release-selection.tsv" \
            --require-policy virustotal-v2 \
            --targets "$RELEASE_TARGETS" \
            --archive-dir "$ARCHIVE_DIR"
          # CLI-only release contract: eight platform archives (four for
          # platforms=linux). Each archive contributes one selected executable
          # plus three runtime sidecars.
          scripts/ci/extract-release-archives.sh "$ARCHIVE_DIR" binaries \
            --targets="$RELEASE_TARGETS" \
            --expect-archives="$EXPECT_ARCHIVES" \
            --expect-binaries="$EXPECT_ARCHIVES" \
            --expect-runtime-files="$EXPECT_RUNTIME_FILES"

      - name: Download the existing candidate VirusTotal evidence
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
        run: |
          gh release download "$VERSION" --repo "$GITHUB_REPOSITORY" --pattern 'release-candidates.tsv' --output "$RUNNER_TEMP/release-candidates.tsv"
          gh release download "$VERSION" --repo "$GITHUB_REPOSITORY" --pattern 'virustotal-candidate-results.tsv' --output "$RUNNER_TEMP/virustotal-candidate-results.tsv"

      - name: Security audits on all unique extracted release objects
        run: |
          # Audit every distinct extracted member/UI-asset byte sequence. The
          # associations manifest retains each source archive's SHA-256.
          # security-strings.sh detects file type and applies binary-only
          # rules (URL allowlist, dangerous-command detection) only to real
          # binaries; for shell scripts it still runs credential and base64
          # pattern audits.
          for f in binaries/objects/*; do
            [ -f "$f" ] || continue
            echo "--- Auditing: $(basename "$f") ---"
            scripts/security-strings.sh "$f"
          done

      # Full-surface VirusTotal pass over the SHIPPED containers.
      #
      # The candidate scan upstream covers executables only. Everything else we
      # actually ship — install.sh, install.ps1, LICENSE, THIRD_PARTY_NOTICES.md,
      # and the unpacked UI assets from the eight CLI archives is extracted
      # here and gets scanned here. Dropping
      # it would have narrowed the promise made in README/SECURITY.md, and
      # install.sh and install.ps1 are the highest-consequence non-executable
      # bytes we publish: users pipe them straight into a shell.
      #
      # The selected executables are NOT re-submitted. They were scanned as
      # candidates, and verify-release-selection.py has just proven every
      # published container carries exactly those bytes — identity is settled by
      # hash, so a second scan adds no assurance.
      #
      # It also is not free, contrary to what this comment used to claim.
      # Measured on v0.10.5: all eight re-submissions produced a NEW analysis
      # (same file-id, timestamp 47 minutes later), and Microsoft's ML engine
      # answered differently for two of them within that hour — in opposite
      # directions. The release notes then cited one scan while the links showed
      # the other. See scripts/ci/exclude-rescanned-selected-objects.sh.
      - name: Withhold already-scanned selected executables
        run: |
          bash scripts/ci/exclude-rescanned-selected-objects.sh \
            binaries/objects "$RUNNER_TEMP/release-selection.tsv" \
            binaries/virustotal-withheld.tsv

      - name: VirusTotal scan of every extracted release object
        uses: crazy-max/ghaction-virustotal@936d8c5c00afe97d3d9a1af26d017cfdf26800a2 # v5.0.0
        id: virustotal
        with:
          vt_api_key: ${{ secrets.VIRUS_TOTAL_SCANNER_API_KEY }}
          files: binaries/objects/*
          request_rate: 4

      # Same policy as the candidate gate: a single Microsoft `!ml` is tolerated
      # and disclosed, anything else blocks. Engine count is evidence, not a gate.
      - name: Wait for VirusTotal results
        env:
          VT_API_KEY: ${{ secrets.VIRUS_TOTAL_SCANNER_API_KEY }}
          VT_ANALYSIS: ${{ steps.virustotal.outputs.analysis }}
          VT_EXPECTED_SCAN_SET: binaries/scan-set.tsv
          VT_ASSOCIATIONS: binaries/associations.tsv
          VT_RESULTS_PATH: binaries/vt-results.tsv
          VT_WITHHELD: binaries/virustotal-withheld.tsv
          MIN_ENGINES: 50
        run: scripts/ci/check-virustotal.sh

      - name: Preserve extracted-object VirusTotal evidence
        if: ${{ always() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: virustotal-evidence-release-${{ github.run_id }}
          path: |
            binaries/associations.tsv
            binaries/scan-set.tsv
            binaries/vt-results.tsv
            binaries/virustotal-withheld.tsv
          if-no-files-found: warn

      - name: Publish durable public VirusTotal evidence
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
          VT_EXPECTED_SCAN_SET: binaries/scan-set.tsv
          VT_ASSOCIATIONS: binaries/associations.tsv
          VT_RESULTS_PATH: binaries/vt-results.tsv
        run: bash scripts/ci/publish-vt-evidence.sh

      # Candidate bytes were scanned before smoke/soak and the verifier above
      # proved every packaged executable has the selected candidate SHA-256.
      # Re-submitting the same executable bytes here would add wait time but no
      # new coverage, so publish the existing per-candidate verdicts instead.
      - name: Append candidate VirusTotal results to release notes
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
          VT_CANDIDATES: ${{ runner.temp }}/release-candidates.tsv
          VT_RESULTS_PATH: ${{ runner.temp }}/virustotal-candidate-results.tsv
          RELEASE_SELECTION: ${{ runner.temp }}/release-selection.tsv
        run: bash scripts/ci/append-vt-notes.sh

  # ── 8. External qualification hold ───────────────────────────
  # Default release behavior stops here after CI verification. The exact draft
  # bytes are then qualified on the qualification host. The promotion workflow validates
  # attached qualification evidence before registries are published or the
  # release is made public.
  qualification-hold:
    needs: [verify]
    if: ${{ !cancelled() && !failure() && needs.verify.result == 'success' && inputs.hold_for_external_qualification }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Record external qualification handoff
        env:
          VERSION: ${{ inputs.version }}
        run: |
          echo "Release $VERSION is verified and remains DRAFT."
          echo "Qualify the exact GitHub release bytes on the qualification host."
          echo "Attach qualification-manifest.json and qualification-summary.md to the draft."
          echo "Then dispatch Promote Qualified Release for the same tag."

  # ── 9. Publish package wrappers (npm + PyPI) ──────────────────
  # Wrappers in pkg/npm and pkg/pypi download the released binary at
  # install time, so they only need a version bump (already in the repo
  # at this point) — no per-release sha256 substitution.
  #
  # Runs against the still-DRAFT GitHub release. If publish fails, the
  # release stays in draft so we can re-run without a half-shipped state.
  publish-registries:
    needs: [verify]
    if: ${{ !cancelled() && !failure() && needs.verify.result == 'success' && !inputs.hold_for_external_qualification && inputs.publish_registries }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # for npm provenance
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # The packaged versions MUST match the dispatched release version —
      # the 0.8.0 release failed here because pkg/npm still carried the
      # previous release's hand-pinned version and npm refuses to publish
      # over an existing version. Inject the dispatch input so a forgotten
      # manual bump can never fail the pipeline again.
      - name: Sync packaging versions to the release version
        env:
          RELEASE_VERSION: ${{ inputs.version }}
        run: |
          V="${RELEASE_VERSION#v}"
          jq --arg v "$V" '.version = $v' pkg/npm/package.json > pkg/npm/package.tmp
          mv pkg/npm/package.tmp pkg/npm/package.json
          sed -i "s/^version = \".*\"/version = \"$V\"/" pkg/pypi/pyproject.toml
          grep -q "\"version\": \"$V\"" pkg/npm/package.json
          grep -q "^version = \"$V\"" pkg/pypi/pyproject.toml
          echo "packaging synced to $V"

      # ── npm ──────────────────────────────────────────────────
      - name: Setup Node
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'

      - name: Publish to npm
        working-directory: pkg/npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
          RELEASE_VERSION: ${{ inputs.version }}
        # A prerelease must never become npm `latest` — plain `npm install`
        # would serve the RC to everyone. Publish prereleases under the
        # `next` dist-tag; testers opt in via `npm i codebase-memory-cli@next`.
        #
        # Idempotency: npm versions are immutable, so a re-run of this job
        # after a partial success (v0.10.1: npm published, then the twine
        # step died) can never republish — it 403s on its own earlier
        # success and the release wedges in draft forever. If the exact
        # version already exists on the registry, publishing is DONE; skip.
        run: |
          V="${RELEASE_VERSION#v}"
          if npm view "codebase-memory-cli@$V" version >/dev/null 2>&1; then
            echo "npm already has codebase-memory-cli@$V — skipping publish (idempotent re-run)"
          elif [[ "$RELEASE_VERSION" == *-* ]]; then
            npm publish --access public --provenance --tag next
          else
            npm publish --access public --provenance
          fi
          # `next` is "the newest you can opt into": once a stable release
          # exists, an older RC must not stay behind it (0.9.1-rc.1 did until
          # v0.12.1). Re-runnable: dist-tag add is idempotent.
          if [[ "$RELEASE_VERSION" != *-* ]]; then
            npm dist-tag add "codebase-memory-cli@$V" next
          fi

      # ── PyPI ─────────────────────────────────────────────────
      - name: Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.12'

      - name: Build PyPI distribution
        working-directory: pkg/pypi
        run: |
          # Every byte of the publish toolchain is bound by hash: version pins
          # alone still let a compromised index serve different content, and a
          # bare `pip install` resolves the whole transitive graph at run time
          # (OSSF Scorecard pinned-dependencies). requirements-publish.txt is
          # generated on a linux/amd64 python:3.12 image — see its header for
          # the exact regeneration command.
          #
          # twine must stay >= 7 and hatchling is pinned in pyproject.toml:
          # `python -m build` resolves its backend fresh in an isolated env, and
          # a hatchling emitting Metadata-Version 2.5 against twine 6.2.0 is
          # what broke the v0.10.1 publish.
          python -m pip install --require-hashes -r requirements-publish.txt
          python -m build
          twine check dist/*

      - name: Publish to PyPI
        working-directory: pkg/pypi
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
        # --skip-existing: PyPI files are immutable like npm versions; a
        # re-run after partial success must treat already-uploaded files
        # as done, not as a fatal collision.
        run: twine upload --non-interactive --skip-existing dist/*

  # ── 10. Atomic un-draft (only after npm + PyPI succeed) ───────
  # The GitHub release stays in DRAFT until both registries publish.
  # If anything upstream fails, keep the failed candidate immutable, fix the
  # source/gate, and issue a new release identity. Never delete and reuse a tag.
  publish-final:
    needs: [verify, publish-registries]
    if: ${{ !cancelled() && !failure() && needs.verify.result == 'success' && needs.publish-registries.result == 'success' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Un-draft GitHub release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
        run: gh release edit "$VERSION" --draft=false --repo "$GITHUB_REPOSITORY"

  # ── 11. GitHub-only prerelease publication ─────────────────────
  # Linux/prerelease route: after verify, make the verified draft a public
  # PRERELEASE (never "latest") without touching npm or PyPI. It is reachable
  # only for a hyphenated version with the external-qualification hold and
  # registry publication both off, so the stable path above is unchanged.
  publish-github-prerelease:
    needs: [verify]
    if: >-
      ${{ !cancelled() && !failure()
      && needs.verify.result == 'success'
      && inputs.publish_github_prerelease
      && inputs.platforms == 'linux'
      && !inputs.hold_for_external_qualification
      && !inputs.publish_registries
      && contains(inputs.version, '-') }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Make the verified draft a public prerelease
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          VERSION: ${{ inputs.version }}
        run: |
          if [[ "$VERSION" != *-* ]]; then
            echo "::error::refusing to publish $VERSION as a prerelease: version has no '-'"
            exit 1
          fi
          gh release edit "$VERSION" --draft=false --prerelease --latest=false --repo "$GITHUB_REPOSITORY"