fix(bb): cache Emscripten .js / .worker.mjs siblings of .wasm targets (into #22815)

.claude/skills/release-network-docs/SKILL.md

@@ -21,12 +21,14 @@ self-identify its release type, ask the user to confirm.
 
 **This skill does NOT:**
 
-- Generate API docs (aztec-nr or TypeScript)
+- Generate developer API docs (aztec-nr or TypeScript)
 - Generate CLI reference docs
 - Update developer version config or cut developer versioned docs
 - Update migration notes
-- Require aztec CLI or nargo (yarn-project build is only needed for node API
-  reference regeneration in Step 5b, which can be skipped)
+- Require aztec CLI, nargo, or yarn-project build
+
+**This skill DOES** regenerate the Node JSON-RPC API reference for the
+versioned docs (see Step 5a).
 
 ## Usage
 
@@ -82,18 +84,6 @@ git tag -l "v<nodeVersion>"
 - If the tag exists but is not checked out: `git checkout v<nodeVersion>`
 - **Abort if the tag doesn't exist** — the release hasn't been tagged yet.
 
-#### Pre-release workflow
-
-If the user provides a target version that differs from the `nodeVersion`
-returned by the RPC (e.g. the network is still running `4.1.3` but the user
-wants to prepare docs for `4.2.0`), this is a **pre-release** docs preparation.
-Ask the user to confirm the target version, then use that version instead of
-`nodeVersion` throughout the remaining steps. The git tag for the target version
-must still exist. Contract addresses from the RPC reflect the *current* network
-state (the old version); they are still valid if the upgrade reuses the same
-contracts, but ask the user to confirm whether any addresses will change at
-upgrade time.
-
 ### Step 3: Identify and Resolve Missing Contract Addresses
 
 The `networks.md` L1 table includes contracts that are **not** returned by
@@ -105,12 +95,8 @@ The Rollup and Registry addresses are already known from the RPC response. Use
 them to query additional addresses on L1. Determine the L1 RPC from the chain
 ID: `1` → Ethereum mainnet, `11155111` → Sepolia.
 
-First check whether the RPC response already includes `gseAddress` in
-`l1ContractAddresses` — newer node versions return it directly. If present,
-use it and skip the on-chain query for GSE.
-
 ```bash
-# GSE (Governance Staking Escrow) — from Rollup (skip if already in RPC response)
+# GSE (Governance Staking Escrow) — from Rollup
 cast call <ROLLUP_ADDRESS> "getGSE()(address)" --rpc-url <L1_RPC>
 
 # Slasher — from Rollup
@@ -182,27 +168,29 @@ Ask the user if any content changes are needed in `docs/docs-operate/`:
 - Operator changelog updates (if not handled by `/updating-changelog`)
 
 If the user has content changes, apply them to the source files in
-`docs/docs-operate/`. If no content changes are needed, skip to Step 5b.
-
-### Step 5b: Regenerate Node API Reference Docs
+`docs/docs-operate/`. If no content changes are needed, skip to Step 5a.
 
-Regenerate the Node JSON-RPC API reference documentation. This script parses the
-TypeScript interface definitions and Zod schemas in `yarn-project/stdlib/src/interfaces/`
-to produce a complete markdown reference for the `node_` and `nodeAdmin_` RPC methods.
+### Step 5a: Regenerate Node API Reference
 
-**Prerequisite:** `yarn-project` must be built (`cd yarn-project && yarn && yarn build`).
-This is the only heavy build dependency for this skill and is only needed for this
-step. If the node API has not changed since the last release, you can skip this step.
+The Node JSON-RPC API reference is auto-generated from TypeScript source. It
+must be regenerated from the release tag's source files to ensure the versioned
+docs reflect the actual API at that release.
 
 ```bash
 cd docs
 yarn generate:node-api-reference
 ```
 
-This updates `docs/docs-operate/operators/reference/node-api-reference.md`.
+This writes to `docs/docs-operate/operators/reference/node-api-reference.md`
+using the source files from the currently checked-out tag. The generator parses
+`yarn-project/stdlib/src/interfaces/aztec-node.ts` and
+`yarn-project/stdlib/src/interfaces/aztec-node-admin.ts` directly (no
+yarn-project build needed, but `yarn-project/node_modules/` must be installed
+so `npx tsx` can resolve `typescript` — run `yarn install` from `yarn-project`
+if needed).
 
-The file is auto-generated — do not hand-edit it. When cutting network versioned
-docs (Step 7), the generated content is included in the snapshot automatically.
+Verify the output lists the expected number of methods and has no ungrouped
+methods warnings.
 
 ### Step 6: Build and Validate
 
@@ -318,11 +306,13 @@ Check for stash conflicts. Then report to the user:
 - **Some addresses are not in the RPC**: Contracts like Staking Registry,
   Reward Booster, Tally Slashing Proposer, and others must be queried on-chain,
   obtained from deployment output, or confirmed unchanged by the user.
-- **Mostly lightweight**: This skill does not require aztec CLI or nargo. The
-  only heavy dependency is `yarn-project` build, needed only for regenerating
-  the node API reference (Step 5b) — skip that step if the node API hasn't
-  changed. Otherwise only `yarn` (for the docs build), `curl`/`jq` (for the
-  RPC query), and `cast` (for on-chain address queries) are needed.
+- **No heavy prerequisites**: This skill does not require aztec CLI, nargo, or
+  a yarn-project build. Only `yarn` (for the docs build), `curl`/`jq` (for
+  the RPC query), and `cast` (for on-chain address queries) are needed.
+- **Node API reference is auto-generated**: Run `yarn generate:node-api-reference`
+  (Step 5a) before building. The generator parses TypeScript source directly, so
+  no yarn-project build is required — but `yarn-project/node_modules/` must exist
+  (run `yarn install` from `yarn-project` if missing).
 - **Build must pass**: Do not cut versioned docs until `yarn build` succeeds.
 - **COMMIT_TAG needs `v` prefix**: The preprocessor uses COMMIT_TAG for GitHub
   URLs and git tag references. Omitting the `v` will break links in versioned

.github/ci3_labels_to_env.sh

@@ -37,6 +37,11 @@ function main {
     echo "NO_FAIL_FAST=1" >> $GITHUB_ENV
   fi
 
+  # Handle skip-compat-e2e label (escape hatch for backwards compat test failures on release PRs)
+  if has_label "ci-skip-compat-e2e"; then
+    echo "SKIP_COMPAT_E2E=1" >> $GITHUB_ENV
+  fi
+
   # Determine CI mode based on event, labels, and target branch
   local ci_mode
   if [ "${GITHUB_EVENT_NAME:-}" == "merge_group" ] || has_label "ci-merge-queue"; then

.github/workflows/aztec-cli-acceptance-test.yml

@@ -0,0 +1,66 @@
+# Validates that a published Aztec CLI release can be installed and used end-to-end.
+# Runs after CI3 completes a tag release (via workflow_run), or manually via workflow_dispatch.
+name: Aztec CLI Acceptance Test
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to install (e.g. latest, nightly, 4.3.0, 4.3.0-nightly.20260420)"
+        required: true
+        type: string
+  workflow_run:
+    workflows: ["CI3"]
+    types:
+      - completed
+    branches:
+      - "v*"
+
+jobs:
+  release-acceptance:
+    runs-on: ubuntu-latest
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'workflow_run'
+       && github.event.workflow_run.conclusion == 'success'
+       && !contains(github.event.workflow_run.head_branch, '-commit.'))
+    timeout-minutes: 30
+    env:
+      VERSION: ${{ github.event.inputs.version || github.event.workflow_run.head_branch }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      # Node is only used to run the .ts harness in run-test.sh, which needs >=22.18 for TS
+      # type-stripping. The aztec CLI installer manages its own node version independently.
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run Aztec CLI acceptance test
+        run: ./aztec-up/test/aztec-cli-acceptance-test/run-test.sh
+
+      - name: Notify Slack on success
+        if: success() && github.event_name != 'workflow_dispatch'
+        env:
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+        run: |
+          export CI=1
+          ./ci3/slack_notify "#team-fairies" \
+            "Aztec CLI Acceptance Test passed for version ${VERSION} :white_check_mark:"
+
+      - name: Notify Slack and dispatch ClaudeBox on failure
+        if: failure() && github.event_name != 'workflow_dispatch'
+        env:
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
+        run: |
+          RUN_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          export CI=1
+          ./ci3/slack_notify_with_claudebox_kickoff "#team-fairies" \
+            "Aztec CLI Acceptance Test FAILED (version ${VERSION}): <${RUN_URL}|View Run>" \
+            "Aztec CLI acceptance test failed for version ${VERSION}. CI run: ${RUN_URL}. Investigate the failure and explain the root cause." \
+            --link "$RUN_URL"

.github/workflows/ci3.yml

@@ -445,3 +445,108 @@ jobs:
           AWS_SHUTDOWN_TIME: 180
         run: |
           ./.github/ci3.sh network-tests-kind
+
+  # Backwards compatibility e2e tests.
+  # Runs e2e tests with contract artifacts from every prior stable release to validate
+  # that new client code works with old contract artifacts ("new pxe / old contracts").
+  # Blocking for stable/RC releases: ci-release-publish requires this job to pass before
+  # publishing. Observational for nightlies: runs, but continue-on-error keeps the workflow
+  # green and ci-release-publish's condition publishes nightlies regardless of the result.
+  # Escape hatch: ci-skip-compat-e2e label makes failures non-blocking on release PRs.
+  ci-compat-e2e:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    needs: [ci]
+    if: |
+      always()
+      && (needs.ci.result == 'success' || needs.ci.result == 'skipped')
+      && github.event.pull_request.head.repo.fork != true
+      && github.event.pull_request.draft == false
+      && (
+        (startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-commit.'))
+        || contains(github.event.pull_request.labels.*.name, 'ci-compat-e2e')
+        || contains(github.event.pull_request.labels.*.name, 'ci-release-pr')
+      )
+    # Non-blocking for nightlies and when ci-skip-compat-e2e escape hatch is applied.
+    continue-on-error: ${{ contains(github.ref_name, '-nightly.') || contains(github.event.pull_request.labels.*.name, 'ci-skip-compat-e2e') }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+          role-session-name: ci3-compat-e2e-${{ github.run_id }}
+          role-duration-seconds: 21600 # 6h – covers AWS_SHUTDOWN_TIME (300 min) + 60 min buffer
+
+      - name: Run Backwards Compatibility E2E Tests
+        timeout-minutes: 330
+        env:
+          GITHUB_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
+          BUILD_INSTANCE_SSH_KEY: ${{ secrets.BUILD_INSTANCE_SSH_KEY }}
+          GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
+          DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          CI3_INSTANCE_PROFILE_NAME: ${{ secrets.CI3_INSTANCE_PROFILE_NAME }}
+          CI3_SECURITY_GROUP_ID: ${{ secrets.CI3_SECURITY_GROUP_ID }}
+          RUN_ID: ${{ github.run_id }}
+          AWS_SHUTDOWN_TIME: 300
+        run: ./.github/ci3.sh compat-e2e
+
+  # Publishes the release (npm, Docker, GitHub release, aztec-up scripts, etc.).
+  # Gated on ci-compat-e2e: a compat regression blocks stable/RC publishing. Nightlies
+  # publish regardless — compat-e2e runs there observationally. Dev `-commit.` tags from
+  # the ci-release-pr flow never reach this job (they are not real releases).
+  ci-release-publish:
+    runs-on: ubuntu-latest
+    environment: master
+    permissions:
+      id-token: write
+      contents: read
+    needs: [ci, ci-compat-e2e]
+    if: |
+      startsWith(github.ref, 'refs/tags/v')
+      && !contains(github.ref_name, '-commit.')
+      && needs.ci.result == 'success'
+      && (
+        contains(github.ref_name, '-nightly.')
+        || needs.ci-compat-e2e.result == 'success'
+      )
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.sha }}
+
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
+          aws-region: us-east-2
+          role-session-name: ci3-release-publish-${{ github.run_id }}
+          role-duration-seconds: 21600
+
+      - name: Run Release Publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
+          BUILD_INSTANCE_SSH_KEY: ${{ secrets.BUILD_INSTANCE_SSH_KEY }}
+          GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
+          GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
+          DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+          CI3_INSTANCE_PROFILE_NAME: ${{ secrets.CI3_INSTANCE_PROFILE_NAME }}
+          CI3_SECURITY_GROUP_ID: ${{ secrets.CI3_SECURITY_GROUP_ID }}
+          RUN_ID: ${{ github.run_id }}
+        run: ./.github/ci3.sh release-publish

.github/workflows/docs-typesense.yml

@@ -27,11 +27,50 @@ jobs:
           fetch-depth: 0
 
       - name: Reindex with Typesense docsearch-scraper
+        env:
+          # Fail the run if the scraper indexes fewer than this many records.
+          # The docsearch-scraper container exits 0 even when its config is broken
+          # and the index ends up nearly empty, so this guard turns a silent
+          # regression (which happened with #22861 dropping the index from
+          # ~12k to 48 records) into a loud CI failure.
+          MIN_HITS: "5000"
+          TYPESENSE_API_KEY: ${{ secrets.TYPESENSE_API_KEY }}
+          TYPESENSE_HOST: ${{ secrets.TYPESENSE_HOST }}
         run: |
+          set -euo pipefail
+
           docker run \
-            -e "TYPESENSE_API_KEY=${{ secrets.TYPESENSE_API_KEY }}" \
-            -e "TYPESENSE_HOST=${{ secrets.TYPESENSE_HOST }}" \
+            -e "TYPESENSE_API_KEY=$TYPESENSE_API_KEY" \
+            -e "TYPESENSE_HOST=$TYPESENSE_HOST" \
             -e "TYPESENSE_PORT=443" \
             -e "TYPESENSE_PROTOCOL=https" \
-            -e "CONFIG=$(cat docs/typesense.config.json | jq -r tostring)" \
-            typesense/docsearch-scraper:0.11.0
+            -e "CONFIG=$(cat docs/typesense.config.json)" \
+            typesense/docsearch-scraper:0.11.0 2>&1 | tee scraper.log
+
+          nb_hits=$(grep -oE 'Nb hits: *[0-9]+' scraper.log | tail -1 | grep -oE '[0-9]+' || true)
+          if [ -z "$nb_hits" ]; then
+            echo "::error::Could not parse 'Nb hits' from scraper output, assuming index is broken."
+            exit 1
+          fi
+          echo "Indexed $nb_hits records (threshold: $MIN_HITS)"
+          if [ "$nb_hits" -lt "$MIN_HITS" ]; then
+            echo "::error::Indexed only $nb_hits records (expected at least $MIN_HITS). Search index is likely broken."
+            exit 1
+          fi
+
+          # Log how many api-nr records are visible in the live index. The
+          # docusaurus theme always prepends `default` to its contextual
+          # docusaurus_tag filter, and no docusaurus page is stamped with
+          # `default` (each carries its plugin-context tag instead), so this
+          # facet count is effectively the count of indexed api-nr records.
+          # Informational only: the count varies with aztec-nr content size.
+          api_hits=$(curl -fsS \
+            "https://$TYPESENSE_HOST/collections/aztec-docs/documents/search" \
+            -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
+            -G \
+            --data-urlencode "q=*" \
+            --data-urlencode "query_by=hierarchy.lvl0" \
+            --data-urlencode "filter_by=docusaurus_tag:=[default]&&language:=en" \
+            --data-urlencode "per_page=1" \
+            | jq -r '.found')
+          echo "api-nr records visible under docusaurus_tag:=[default]: $api_hits"