test(cli): qualify released Runtime Host State Roots

.github/workflows/cli-package-validation.yml

@@ -41,6 +41,9 @@ on:
       - 'packages/storage/src/native-file-lock.ts'
       - 'scripts/generate-runtime-host-peer-*'
       - 'scripts/release-cli-package.mjs'
+      - 'scripts/qualify-released-cli-state-root.mjs'
+      - 'scripts/qualify-released-cli-state-root.test.mjs'
+      - 'scripts/released-cli-state-root-fixture.mjs'
       - 'scripts/smoke-release-cli-package.mjs'
   workflow_call:
     inputs:
@@ -61,6 +64,15 @@ on:
       release_candidate_run_attempt:
         description: Workflow attempt that built the immutable artifact
         value: ${{ jobs.build.outputs.release_candidate_run_attempt }}
+      release_predecessor_version:
+        description: Exact npm Nightly version qualified against this candidate
+        value: ${{ jobs.release-predecessor.outputs.version }}
+      release_predecessor_tarball_url:
+        description: Exact npm Nightly tarball qualified against this candidate
+        value: ${{ jobs.release-predecessor.outputs.tarball_url }}
+      release_predecessor_integrity:
+        description: npm SHA-512 integrity of the Nightly tarball qualified against this candidate
+        value: ${{ jobs.release-predecessor.outputs.integrity }}
   workflow_dispatch:
 
 permissions:
@@ -70,6 +82,26 @@ concurrency:
   group: cli-package-validation-${{ github.workflow }}-${{ github.ref }}
 
 jobs:
+  release-predecessor:
+    name: Resolve immutable release predecessor
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    outputs:
+      version: ${{ steps.predecessor.outputs.version }}
+      tarball_url: ${{ steps.predecessor.outputs.tarball_url }}
+      integrity: ${{ steps.predecessor.outputs.integrity }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.source_commit || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+      - name: Resolve the current npm Nightly as immutable evidence
+        id: predecessor
+        run: node scripts/release-cli-publication.mjs resolve-nightly-predecessor "$GITHUB_OUTPUT"
+
   peer-native:
     name: Build direct-peer addon (${{ matrix.target }})
     runs-on: ${{ matrix.runner }}
@@ -276,6 +308,133 @@ jobs:
       - name: Validate the installed tarball
         run: node scripts/smoke-release-cli-package.mjs
 
+  state-root-qualification:
+    name: Qualify released State Root (${{ matrix.name }})
+    needs: [build, release-predecessor]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: cross epoch 74 to 76
+            source_url: https://registry.npmjs.org/maka-agent/-/maka-agent-0.2.0-dev.3.20260830.tgz
+            source_sha256: 66b1ce9307c9d5c06eaa7a6cbf533d4747d02caf71c1776c69c7dbfa12c3f414
+            target_kind: published
+            target_url: https://registry.npmjs.org/maka-agent/-/maka-agent-0.2.0-dev.4.20260830.tgz
+            target_sha256: b7d48adb466e16be7ffefbda3a0fcd833cc4108ea502b27778d0f4da680e1fc0
+            epoch_relation: different
+          - name: same epoch 76
+            source_url: https://registry.npmjs.org/maka-agent/-/maka-agent-0.2.0-dev.4.20260830.tgz
+            source_sha256: b7d48adb466e16be7ffefbda3a0fcd833cc4108ea502b27778d0f4da680e1fc0
+            target_kind: published
+            target_url: https://registry.npmjs.org/maka-agent/-/maka-agent-0.2.0-dev.5.20260830.tgz
+            target_sha256: e7a682157c6899fc7f1be86a2d7b0bd0696195a5771d8cc97bd1389a5b74989f
+            epoch_relation: same
+          - name: current Nightly predecessor to candidate
+            source_url: ${{ needs.release-predecessor.outputs.tarball_url }}
+            source_sha256: ''
+            source_integrity: ${{ needs.release-predecessor.outputs.integrity }}
+            target_kind: candidate
+            target_url: ''
+            target_sha256: ''
+            epoch_relation: any
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.source_commit || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+      - name: Select the release npm toolchain
+        run: npm install --global --no-audit --no-fund "$(node -p 'require("./package.json").packageManager')"
+      - name: Require the account-isolation sandbox
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes bubblewrap
+          bwrap --version
+      - name: Download the release candidate
+        if: matrix.target_kind == 'candidate'
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          artifact-ids: ${{ needs.build.outputs.release_candidate_artifact_id }}
+          path: packages/cli/release
+      - name: Prepare exact source and target artifacts
+        env:
+          SOURCE_URL: ${{ matrix.source_url }}
+          SOURCE_SHA256: ${{ matrix.source_sha256 }}
+          SOURCE_INTEGRITY: ${{ matrix.source_integrity }}
+          TARGET_KIND: ${{ matrix.target_kind }}
+          TARGET_URL: ${{ matrix.target_url }}
+          TARGET_SHA256: ${{ matrix.target_sha256 }}
+        run: |
+          set -euo pipefail
+          evidence_root="$RUNNER_TEMP/released-state-root"
+          mkdir -p "$evidence_root"
+          source_path="$evidence_root/source.tgz"
+          curl --fail --location --max-filesize 67108864 --proto '=https' --tlsv1.2 "$SOURCE_URL" --output "$source_path"
+          source_sha256="$SOURCE_SHA256"
+          if [[ -n "$SOURCE_INTEGRITY" ]]; then
+            node - "$source_path" "$SOURCE_INTEGRITY" <<'NODE'
+          const { createHash } = require('node:crypto');
+          const { readFileSync } = require('node:fs');
+          const bytes = readFileSync(process.argv[2]);
+          const actual = `sha512-${createHash('sha512').update(bytes).digest('base64')}`;
+          if (actual !== process.argv[3]) throw new Error('Source tarball integrity mismatch');
+          NODE
+            source_sha256="$(sha256sum "$source_path" | cut -d ' ' -f 1)"
+          else
+            test -n "$source_sha256"
+          fi
+          if [[ "$TARGET_KIND" == 'published' ]]; then
+            target_path="$evidence_root/target.tgz"
+            curl --fail --location --max-filesize 67108864 --proto '=https' --tlsv1.2 "$TARGET_URL" --output "$target_path"
+            target_sha256="$TARGET_SHA256"
+          else
+            target_path="$(find packages/cli/release -maxdepth 1 -name '*.tgz' -print -quit)"
+            test -n "$target_path"
+            target_path="$(realpath "$target_path")"
+            target_sha256="$(sha256sum "$target_path" | cut -d ' ' -f 1)"
+          fi
+          {
+            echo "SOURCE_PATH=$source_path"
+            echo "SOURCE_SHA256=$source_sha256"
+            echo "TARGET_PATH=$target_path"
+            echo "TARGET_SHA256=$target_sha256"
+          } >> "$GITHUB_ENV"
+      - name: Qualify the released State Root transition
+        env:
+          EXPECTED_EPOCH_RELATION: ${{ matrix.epoch_relation }}
+          MAKA_QUALIFICATION_BWRAP_USE_SUDO: '1'
+        run: |
+          set -o pipefail
+          npm run --silent release:cli:qualify-state-root -- \
+            --source "$SOURCE_PATH" \
+            --source-sha256 "$SOURCE_SHA256" \
+            --target "$TARGET_PATH" \
+            --target-sha256 "$TARGET_SHA256" \
+            --expect-epoch-relation "$EXPECTED_EPOCH_RELATION" \
+            | tee "$RUNNER_TEMP/released-state-root-report.json"
+      - name: Preserve the qualification report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: released-state-root-${{ strategy.job-index }}
+          path: ${{ runner.temp }}/released-state-root-report.json
+          if-no-files-found: error
+          retention-days: 7
+      - name: Require the qualified Nightly predecessor to remain current
+        if: matrix.target_kind == 'candidate'
+        env:
+          PREDECESSOR_VERSION: ${{ needs.release-predecessor.outputs.version }}
+          PREDECESSOR_TARBALL_URL: ${{ needs.release-predecessor.outputs.tarball_url }}
+          PREDECESSOR_INTEGRITY: ${{ needs.release-predecessor.outputs.integrity }}
+        run: |
+          node scripts/release-cli-publication.mjs assert-nightly-predecessor \
+            "$PREDECESSOR_VERSION" \
+            "$PREDECESSOR_TARBALL_URL" \
+            "$PREDECESSOR_INTEGRITY"
+
   eval:
     name: Validate installed CLI Eval
     if: github.event_name != 'pull_request'

.github/workflows/npm-publication.yml

@@ -144,10 +144,17 @@ jobs:
             "$NIGHTLY_VERSION" \
             "$GITHUB_OUTPUT"
 
-      - name: Require the Nightly channel to advance
+      - name: Require the qualified predecessor and Nightly channel advance
         env:
           NIGHTLY_VERSION: ${{ steps.npm-nightly.outputs.version }}
+          PREDECESSOR_VERSION: ${{ needs.cli.outputs.release_predecessor_version }}
+          PREDECESSOR_TARBALL_URL: ${{ needs.cli.outputs.release_predecessor_tarball_url }}
+          PREDECESSOR_INTEGRITY: ${{ needs.cli.outputs.release_predecessor_integrity }}
         run: |
+          node scripts/release-cli-publication.mjs assert-nightly-predecessor \
+            "$PREDECESSOR_VERSION" \
+            "$PREDECESSOR_TARBALL_URL" \
+            "$PREDECESSOR_INTEGRITY"
           current="$(npm view maka-agent dist-tags.nightly --registry https://registry.npmjs.org/)"
           node scripts/product-nightly.mjs assert-channel-advance "$NIGHTLY_VERSION" "$current"
 

.github/workflows/release-cli-stage.yml

@@ -175,11 +175,19 @@ jobs:
       - name: Submit the candidate to npm staging
         env:
           GH_TOKEN: ${{ github.token }}
+          PREDECESSOR_VERSION: ${{ needs.validate.outputs.release_predecessor_version }}
+          PREDECESSOR_TARBALL_URL: ${{ needs.validate.outputs.release_predecessor_tarball_url }}
+          PREDECESSOR_INTEGRITY: ${{ needs.validate.outputs.release_predecessor_integrity }}
           PRODUCT_SOURCE_COMMIT: ${{ needs.authorize.outputs.source_commit }}
           PRODUCT_TAG: ${{ needs.authorize.outputs.product_tag }}
           RELEASE_DIST_TAG: ${{ steps.release.outputs.dist_tag }}
           RELEASE_TARBALL: ${{ steps.release.outputs.tarball }}
         run: |
+          node scripts/release-cli-publication.mjs assert-nightly-predecessor \
+            "$PREDECESSOR_VERSION" \
+            "$PREDECESSOR_TARBALL_URL" \
+            "$PREDECESSOR_INTEGRITY"
+
           node scripts/product-release-authority.mjs verify-draft \
             "$PRODUCT_TAG" "$PRODUCT_SOURCE_COMMIT" "$GITHUB_REPOSITORY"
 

package.json

@@ -55,6 +55,7 @@
     "check:cli-third-party-notices": "node scripts/generate-third-party-notices.mjs --target cli --check",
     "release:cli:pack": "node scripts/release-cli-package.mjs",
     "release:cli:smoke": "node scripts/smoke-release-cli-package.mjs",
+    "release:cli:qualify-state-root": "node scripts/qualify-released-cli-state-root.mjs",
     "release:cli:eval": "node scripts/release-cli-eval-package.mjs",
     "check:app-shell-hooks": "node scripts/check-app-shell-hooks.mjs",
     "check:asf-headers": "node scripts/asf-license-headers.mjs check",
@@ -74,7 +75,7 @@
     "check:runtime-host-peer-dependencies": "node scripts/generate-runtime-host-peer-dependencies.mjs --check",
     "generate:runtime-host-peer-notices": "node scripts/generate-runtime-host-peer-notices.mjs",
     "check:runtime-host-peer-notices": "node scripts/generate-runtime-host-peer-notices.mjs --check",
-    "check:release": "npm run check:stale && npm run check:third-party-notices && npm run check:cli-third-party-notices && npm run check:model-metadata && npm run check:product-release-identity && npm run check:asf-npm && node --test scripts/product-nightly.test.mjs scripts/desktop-nightly.test.mjs scripts/desktop-nightly-stage.test.mjs scripts/desktop-nightly-release.test.mjs scripts/desktop-nightly-workflow-policy.test.mjs scripts/product-release.test.mjs scripts/product-release-authority.test.mjs scripts/release-cli-file-policy.test.mjs scripts/release-cli-artifact-policy.test.mjs scripts/release-cli-eval-support.test.mjs scripts/release-cli-publication.test.mjs scripts/release-cli-runtime-host-diagnostics.test.mjs scripts/release-cli-workflow-policy.test.mjs scripts/verify-packaged-app.test.mjs scripts/third-party-closure.test.mjs scripts/generate-third-party-notices.test.mjs scripts/source-legal-inventory.test.mjs scripts/sync-model-metadata.test.mjs scripts/windows-package-source-closure.test.mjs",
+    "check:release": "npm run check:stale && npm run check:third-party-notices && npm run check:cli-third-party-notices && npm run check:model-metadata && npm run check:product-release-identity && npm run check:asf-npm && node --test scripts/product-nightly.test.mjs scripts/desktop-nightly.test.mjs scripts/desktop-nightly-stage.test.mjs scripts/desktop-nightly-release.test.mjs scripts/desktop-nightly-workflow-policy.test.mjs scripts/product-release.test.mjs scripts/product-release-authority.test.mjs scripts/release-cli-file-policy.test.mjs scripts/release-cli-artifact-policy.test.mjs scripts/release-cli-eval-support.test.mjs scripts/release-cli-publication.test.mjs scripts/release-cli-runtime-host-diagnostics.test.mjs scripts/qualify-released-cli-state-root.test.mjs scripts/release-cli-workflow-policy.test.mjs scripts/verify-packaged-app.test.mjs scripts/third-party-closure.test.mjs scripts/generate-third-party-notices.test.mjs scripts/source-legal-inventory.test.mjs scripts/sync-model-metadata.test.mjs scripts/windows-package-source-closure.test.mjs",
     "package:macos-arm64": "node scripts/package-macos-arm64.mjs",
     "verify:macos-arm64": "node scripts/verify-macos-arm64-dmg.mjs",
     "package:macos-autoupdate-next": "node scripts/package-macos-autoupdate-next.mjs",