release: promote verified Bitcoin Explorer baseline

.github/workflows/backend-integration.yml

@@ -2,6 +2,7 @@ name: Backend Integration Tests with MariaDB
 
 on:
   pull_request:
+    branches: [master]
     types: [opened, review_requested, synchronize]
   push:
     branches:
@@ -15,6 +16,10 @@ jobs:
         node: ["24.13.0"]
       fail-fast: false
     runs-on: mempool-ci
+    env:
+      COMPOSE_PROJECT_NAME: mempool-integration-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
+      MEMPOOL_TEST_BASE_CONFIG_FILE: ${{ github.workspace }}/${{ matrix.node }}/integration/backend/mempool-config.test.json
+      MEMPOOL_TEST_RUNTIME_CONFIG_FILE: ${{ github.workspace }}/${{ matrix.node }}/integration/backend/.mempool-config.integration.json
 
     name: Backend Integration Tests - node ${{ matrix.node }}
 
@@ -87,7 +92,8 @@ jobs:
           npm run test:integration
         working-directory: ${{ matrix.node }}/integration/backend
         env:
-          MEMPOOL_CONFIG_FILE: ${{ github.workspace }}/${{ matrix.node }}/integration/backend/mempool-config.test.json
+          MEMPOOL_CONFIG_FILE: ${{ env.MEMPOOL_TEST_RUNTIME_CONFIG_FILE }}
+          SKIP_DB_TEARDOWN: '1'
 
       - name: Start MariaDB for server test
         run: docker compose -f docker-compose.test.yml up -d
@@ -129,7 +135,7 @@ jobs:
           fi
         working-directory: ${{ matrix.node }}/integration/backend
         env:
-          MEMPOOL_CONFIG_FILE: ${{ github.workspace }}/${{ matrix.node }}/integration/backend/mempool-config.test.json
+          MEMPOOL_CONFIG_FILE: ${{ env.MEMPOOL_TEST_RUNTIME_CONFIG_FILE }}
 
       - name: Cleanup containers
         if: always()

.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI Pipeline for the Backend and Frontend
 
 on:
   pull_request:
+    branches: [master]
     types: [opened, review_requested, synchronize]
   push:
     branches:

.github/workflows/docker.yml

@@ -11,6 +11,7 @@ on:
       - v[0-9]+.[0-9]+.[0-9]+
       - v[0-9]+.[0-9]+.[0-9]+-*
   pull_request:
+    branches: [master]
     types: [opened, synchronize, reopened, labeled]
 
 permissions:

.github/workflows/universe-ci.yml

@@ -2,7 +2,7 @@ name: Universe CI
 
 on:
   push:
-    branches: [develop, main]
+    branches: [main]
   pull_request:
     branches: [develop, main]
   workflow_dispatch:
@@ -12,7 +12,7 @@ permissions:
 
 concurrency:
   group: universe-ci-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: false
 
 jobs:
   docs:
@@ -40,6 +40,9 @@ jobs:
       - name: Every dynamic palette carries a readable foreground
         run: node scripts/universe/check-palettes.mjs
 
+      - name: Every filled surface declares the ink on it
+        run: node scripts/universe/check-fills.mjs
+
       - name: Contrast arithmetic is correct
         run: node --test scripts/universe/contrast.test.mjs
 
@@ -52,10 +55,17 @@ jobs:
       - name: Gateway routing
         run: node --test scripts/universe/gateway.test.mjs
 
+      - name: The gateway bridges an upstream restart rather than failing
+        run: node --test scripts/universe/gateway-restart.test.mjs
+
   backend:
     name: Backend build and test
     runs-on: [self-hosted, linux-ultra]
     timeout-minutes: 45
+    env:
+      COMPOSE_PROJECT_NAME: mempool-integration-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
+      MEMPOOL_TEST_BASE_CONFIG_FILE: ${{ github.workspace }}/backend/mempool-config.test.json
+      MEMPOOL_TEST_RUNTIME_CONFIG_FILE: ${{ github.workspace }}/backend/.mempool-config.integration.json
     steps:
       - name: Checkout
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
@@ -83,10 +93,24 @@ jobs:
         working-directory: backend
         run: npm run test:ci
 
+      # The failure that shipped was a configuration one: the migrations never
+      # ran against the engine production uses, so nothing caught the syntax it
+      # rejects. These run the real backend against a real database.
+      - name: Migrations and repositories against a real database
+        working-directory: backend
+        run: npm run test:integration
+        env:
+          MEMPOOL_CONFIG_FILE: ${{ env.MEMPOOL_TEST_RUNTIME_CONFIG_FILE }}
+
   frontend:
     name: Frontend build
     runs-on: [self-hosted, linux-ultra]
-    timeout-minutes: 60
+    # The deep visual pass measured 48 minutes once the gated route list grew
+    # from three routes to seven, which put the job over the hour it had and
+    # killed it three minutes from the end. A gate that cannot finish protects
+    # nothing, which is the same reason the matrix was split in two to begin
+    # with. Budget is for the pass that actually runs, with room to grow.
+    timeout-minutes: 100
     steps:
       - name: Checkout
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
@@ -123,26 +147,73 @@ jobs:
       - name: Every asset the build references is in the output
         run: node scripts/universe/check-build-assets.mjs
 
+      - name: No em dash in what the build actually ships
+        run: node scripts/universe/check-text.mjs frontend/dist
+
       - name: Install the visual QA harness
         working-directory: scripts/universe/visual-qa
         run: npm ci
 
+      - name: The unfinished-page gate fires on the states that shipped
+        working-directory: scripts/universe/visual-qa
+        run: node --test progress-gate.test.mjs
+
+      # A fixed port here once measured another job's build: two runners share
+      # a host, the second gateway crashed on the taken port behind "&", the
+      # probe happily reached the first job's server, and the run died halfway
+      # when that other job ended. Each run now serves on its own free port and
+      # refuses to continue unless the process answering is the one it started.
       - name: Serve the built frontend
         run: |
-          UNIVERSE_GATEWAY_PORT=8123           UNIVERSE_GATEWAY_ROOT=frontend/dist/mempool/browser           node scripts/universe/gateway.mjs &
+          GATEWAY_PORT=$(node -e "const s=require('net').createServer();s.listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close()})")
+          echo "GATEWAY_PORT=$GATEWAY_PORT" >> "$GITHUB_ENV"
+          UNIVERSE_GATEWAY_PORT=$GATEWAY_PORT           UNIVERSE_GATEWAY_ROOT=frontend/dist/mempool/browser           node scripts/universe/gateway.mjs &
+          GATEWAY_PID=$!
           for i in $(seq 1 30); do
-            curl -fsS -o /dev/null http://127.0.0.1:8123/ && break
+            curl -fsS -o /dev/null "http://127.0.0.1:$GATEWAY_PORT/" && break
             sleep 1
           done
+          kill -0 "$GATEWAY_PID"
+          curl -fsS "http://127.0.0.1:$GATEWAY_PORT/__gateway/health"
+
+      # The harness fails the run when a page never finishes loading, when a
+      # chart panel draws nothing, or when a failure state says nothing about
+      # why. Those three states passed every other gate here and shipped.
+      #
+      # Split into two passes that finish, rather than one sweep that does not.
+      # Every combination of thirteen routes, seven data states, three themes
+      # and seven widths is nineteen hundred page loads, which does not fit the
+      # job timeout, and a gate that cannot finish protects nothing.
+      #
+      # The broad pass walks every route at a phone and a desktop width with
+      # real data, which is where overflow, broken images and a page that never
+      # finishes show up. The deep pass takes the routes this suite holds to a
+      # terminal state through every failure state, every theme and the widths
+      # that change the layout, which is where a page that lies about why it is
+      # empty shows up. Measured at about two and a half minutes and sixteen
+      # minutes respectively.
+      - name: Every route renders and finishes, at a phone and a desktop width
+        working-directory: scripts/universe/visual-qa
+        run: >-
+          node capture.mjs --base=http://127.0.0.1:$GATEWAY_PORT --out=./artifacts-broad
+          --states=populated --themes=default --viewports=375,1440
+
+      - name: The gated routes hold up across themes, widths and every failure state
+        working-directory: scripts/universe/visual-qa
+        run: >-
+          node capture.mjs --base=http://127.0.0.1:$GATEWAY_PORT --out=./artifacts
+          --routes=graphs,mining,protocols,home,blocks,tx,address --viewports=320,768,1440
 
-      - name: Measured contrast, accessibility, overflow, and screenshots
+      - name: Forced colours and 200 percent zoom
         working-directory: scripts/universe/visual-qa
-        run: node capture.mjs --base=http://127.0.0.1:8123 --out=./artifacts
+        run: node modes-check.mjs --base=http://127.0.0.1:$GATEWAY_PORT
 
       - name: Keep the contrast report and the route screenshots
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: universe-visual-qa
-          path: scripts/universe/visual-qa/artifacts
+          path: |
+            scripts/universe/visual-qa/artifacts
+            scripts/universe/visual-qa/artifacts-broad
           retention-days: 30

.github/workflows/universe-production-smoke.yml

@@ -0,0 +1,44 @@
+name: Universe production smoke
+
+# Checks the live origin with nothing mocked.
+#
+# The rest of the suite answers every request from fixtures, which is what let
+# a release ship with a Charts page and a Mining dashboard in front of routes
+# that answered 404. Fixtures prove how a page renders given data; only this
+# proves the deployment can produce any.
+
+on:
+  # After a release, and on a schedule so a dependency that fails later is
+  # noticed without anyone deploying.
+  workflow_dispatch:
+    inputs:
+      origin:
+        description: Origin to check
+        required: false
+        default: https://explorer.bitcoinuniverse.io
+  schedule:
+    - cron: '17 * * * *'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: universe-production-smoke
+  cancel-in-progress: false
+
+jobs:
+  smoke:
+    name: Live origin answers with real content
+    runs-on: [self-hosted, linux-ultra]
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24.19.0'
+
+      - name: Every advertised feature has routes, data, and a matching release
+        run: node scripts/universe/synthetic-check.mjs "${{ github.event.inputs.origin || 'https://explorer.bitcoinuniverse.io' }}"

.github/workflows/universe-release-artifact.yml

@@ -0,0 +1,113 @@
+name: Universe release artifact
+
+# Builds the one artifact a release installs, on the runner fleet.
+#
+# It exists because the artifact used to be built on a workstation, and that
+# machine has two ways of handing you a stale build without saying so: a
+# leftover server process keeps serving an old output directory, and a failed
+# build step can leave the previous output in place. Both have already produced
+# a measurement that described a build nobody was running. A runner starts from
+# a clean checkout every time, so the artifact matches the commit it names.
+
+# It builds the ref it is dispatched on, and takes no ref input. An input
+# would be more convenient and is not safe: dispatched from the default
+# branch, the job holds that branch's Actions cache scope, so building an
+# arbitrary ref would run that ref's install and build scripts with write
+# access to the cache every other workflow here restores from. Dispatch it
+# against the branch or tag you want built instead.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  artifact:
+    name: Build and pack
+    runs-on: [self-hosted, linux-ultra]
+    timeout-minutes: 90
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Record what is being built
+        id: sha
+        run: |
+          sha=$(git rev-parse HEAD)
+          printf 'sha=%s\n' "$sha" >> "$GITHUB_OUTPUT"
+          printf 'short=%s\n' "${sha:0:9}" >> "$GITHUB_OUTPUT"
+          printf 'Building %s (%s)\n' "$sha" "$(git log -1 --format=%s)"
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24.19.0'
+
+      - name: Install backend
+        working-directory: backend
+        run: npm ci
+
+      - name: Build backend
+        working-directory: backend
+        run: npm run build
+
+      - name: Install frontend
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: frontend
+        run: npm run build:universe
+
+      # The same gates the CI run applies to a build, applied to the build that
+      # is about to be shipped. A green CI run on the same commit does not prove
+      # this output is sound, because this is a different build.
+      - name: Built bundle carries no upstream marks
+        run: node scripts/universe/check-branding.mjs frontend/dist
+
+      - name: Built bundle calls no third-party origin
+        run: node scripts/universe/check-origins.mjs frontend/dist
+
+      - name: Every asset the build references is in the output
+        run: node scripts/universe/check-build-assets.mjs
+
+      - name: No em dash in what the build actually ships
+        run: node scripts/universe/check-text.mjs frontend/dist
+
+      # release.sh reads the frontend from frontend/build, the backend from
+      # backend/dist, and the gateway from scripts/universe. node_modules and
+      # the compiled gbt module are not packed: install hard-links them from the
+      # running release, which is correct only while the dependency tree is
+      # unchanged. The lock file is packed so that release.sh install can
+      # compare it against the running release and refuse the hard link when it
+      # differs. That check belongs there, where both trees are visible; here
+      # only one of them is.
+      - name: Pack
+        id: pack
+        run: |
+          set -euo pipefail
+          sha='${{ steps.sha.outputs.short }}'
+          stage=$(mktemp -d)
+          mkdir -p "$stage/backend" "$stage/frontend" "$stage/scripts"
+          cp -a backend/dist "$stage/backend/dist"
+          cp -a backend/package.json "$stage/backend/package.json"
+          cp -a backend/package-lock.json "$stage/backend/package-lock.json"
+          cp -a frontend/dist/mempool/browser "$stage/frontend/build"
+          cp -a scripts/universe "$stage/scripts/universe"
+          test -f "$stage/backend/dist/index.js"
+          test -f "$stage/frontend/build/index.html"
+          test -f "$stage/scripts/universe/gateway.mjs"
+          out="$PWD/mempool-$sha.tar.gz"
+          tar -czf "$out" -C "$stage" backend frontend scripts
+          sha256sum "$out" | tee "$out.sha256"
+          printf 'name=mempool-%s\n' "$sha" >> "$GITHUB_OUTPUT"
+
+      - name: Upload
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: ${{ steps.pack.outputs.name }}
+          path: |
+            mempool-*.tar.gz
+            mempool-*.tar.gz.sha256
+          retention-days: 14
+          if-no-files-found: error

.gitignore

@@ -15,4 +15,7 @@ node_modules/
 
 # Visual QA working output. Curated review sets are committed under docs/design.
 scripts/universe/visual-qa/artifacts/
+scripts/universe/visual-qa/verify*/
+# Any output directory the harness is pointed at, not just the default one.
+scripts/universe/visual-qa/artifacts-*/
 scripts/universe/visual-qa/node_modules/

backend/docker-compose.test.yml

@@ -2,15 +2,20 @@ version: "3.7"
 
 services:
   db-test:
-    image: mariadb:10.5.21
+    # Must stay the same engine and major version the Universe deployment runs.
+    # The migrations use MariaDB syntax that MySQL rejects outright, so a test
+    # database on a different engine proves nothing about the release.
+    image: mariadb:11.4
     environment:
       MYSQL_DATABASE: "mempool_test"
       MYSQL_USER: "mempool_test"
       MYSQL_PASSWORD: "mempool_test"
       MYSQL_ROOT_PASSWORD: "admin"
       MARIADB_AUTO_UPGRADE: "1"
     ports:
-      - "33306:3306"
+      # Jest requests port zero so Docker reserves an unused port atomically.
+      # The shell-managed local test path keeps its established 33306 default.
+      - "127.0.0.1:${MEMPOOL_TEST_DB_PORT:-33306}:3306"
     healthcheck:
       test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "mempool_test", "-pmempool_test"]
       interval: 5s