From 77a30edb31cec756b7de02f4d8742d1913fcb81a Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 00:36:28 +0300 Subject: [PATCH 01/14] ci: ignore local docs/superpowers/ directory Holds design specs and implementation plans generated during brainstorming/planning sessions. These are local working artifacts, not part of the repo. --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index ba22360d98..2eff007849 100644 --- a/.gitignore +++ b/.gitignore @@ -49,4 +49,7 @@ documentation/doxygen/latex *.pyc *.pyo *.egg-info/ -build \ No newline at end of file +build + +# Local design specs and implementation plans (not part of repo) +docs/superpowers/ \ No newline at end of file From ee8efce65c59cd0a8603d8798bb31a7cc668c9f7 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 00:40:58 +0300 Subject: [PATCH 02/14] ci: add BuildKit cache mounts and scope make target in production Dockerfile Adds --mount=type=cache for ccache (/root/.ccache, named id=viz-ccache) and apt (/var/cache/apt + /var/lib/apt/lists), restricts make to the vizd target, and emits ccache -s for hit-rate visibility. Removes the docker-clean apt hook so cache mounts actually persist. The final cleanup that ran apt-get clean and rm -rf /var/lib/apt/lists on the apt step has been deleted; cache mounts are unmounted before the next RUN executes and the builder stage is discarded anyway. No behavior change to the produced production image. Caching only takes effect once docker-pr-build.yml and docker-main.yml are updated to pass cache-from/cache-to to docker/build-push-action@v6. --- share/vizd/docker/Dockerfile-production | 40 ++++++++++++++++++++----- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/share/vizd/docker/Dockerfile-production b/share/vizd/docker/Dockerfile-production index 4c7a953261..b8d21ccc47 100644 --- a/share/vizd/docker/Dockerfile-production +++ b/share/vizd/docker/Dockerfile-production @@ -1,10 +1,29 @@ +# syntax=docker/dockerfile:1.4 FROM phusion/baseimage:noble-1.0.3 AS builder ENV LANG=en_US.UTF-8 ENV APPDIR=/usr/local/src/viz/ ENV HOME=/var/lib/vizd -RUN \ +# ccache configuration (cache directory is provided as a BuildKit cache mount below). +ENV CCACHE_DIR=/root/.ccache +ENV CCACHE_MAXSIZE=2G +ENV CCACHE_COMPRESS=1 + +# Install build dependencies. +# +# IMPORTANT: the `rm -f /etc/apt/apt.conf.d/docker-clean` line is required. +# Ubuntu/Debian base images ship an apt hook that auto-deletes +# /var/cache/apt/archives after every apt run, which silently defeats the +# BuildKit cache mount on /var/cache/apt. Do not remove this rm. +# +# We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` +# at the end, because those paths are mounted as BuildKit caches that we want +# to persist across CI runs. The builder stage is discarded in the final image +# regardless, so leftover cache contents have no effect on the production image. +RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ + --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \ + rm -f /etc/apt/apt.conf.d/docker-clean && \ for i in 1 2 3; do \ apt-get update && \ apt-get install -y --no-install-recommends \ @@ -40,9 +59,7 @@ RUN \ pkg-config \ zlib1g-dev && \ break || sleep 10; \ - done && \ - apt-get clean && \ - rm -rf /var/lib/apt/lists/* + done # Explicitly copy needed files to avoid re-building when changing other files COPY .git $APPDIR/.git @@ -52,11 +69,16 @@ COPY thirdparty $APPDIR/thirdparty COPY plugins $APPDIR/plugins COPY libraries $APPDIR/libraries -RUN \ +# Build vizd. The named cache mount `viz-ccache` is shared across all VIZ +# Dockerfiles so that production and testnet builds in the same workflow +# benefit from each other's compiled-object cache. `make -j$(nproc) vizd` +# (instead of unscoped `make`) skips cli_wallet, util programs, and tests +# that are not installed into the production image. +RUN --mount=type=cache,target=/root/.ccache,id=viz-ccache,sharing=locked \ cd $APPDIR && \ git submodule update --init --recursive -f && \ sed -i '/add_subdirectory(tests)/d' thirdparty/fc/CMakeLists.txt && \ - mkdir build && \ + mkdir -p build && \ cd build && \ cmake \ -DCMAKE_BUILD_TYPE=Release \ @@ -66,13 +88,17 @@ RUN \ -DENABLE_MONGO_PLUGIN=FALSE \ .. \ && \ - make -j$(nproc) + make -j$(nproc) vizd && \ + ccache -s RUN set -xe ;\ cd $APPDIR/build ;\ make install ;\ rm -rf $APPDIR +# Final cleanup of the builder stage. apt cache mounts above are not affected +# by these rm/clean calls because cache mounts are unmounted by the time this +# RUN executes; this only removes anything that landed in real layers. RUN \ apt-get clean && \ apt-get autoremove -y && \ From b41d0cad1d0bbbaeeb86817ab3b1ab7cfe92d12e Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 07:30:34 +0300 Subject: [PATCH 03/14] ci: clarify cache-mount and ccache rationale in production Dockerfile Comment-only follow-up to ee8efce. Addresses code-review feedback: - CCACHE_MAXSIZE=2G now has the GHA-quota rationale inline. - The docker-clean apt hook comment mentions both /var/cache/apt/archives and /var/lib/apt/lists (both are mounted, both are wiped by the hook). - The build RUN comment explains why sharing=locked is required (ccache is not concurrent-safe). No logic or directive change. --- share/vizd/docker/Dockerfile-production | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/share/vizd/docker/Dockerfile-production b/share/vizd/docker/Dockerfile-production index b8d21ccc47..ec4cc8e427 100644 --- a/share/vizd/docker/Dockerfile-production +++ b/share/vizd/docker/Dockerfile-production @@ -6,6 +6,12 @@ ENV APPDIR=/usr/local/src/viz/ ENV HOME=/var/lib/vizd # ccache configuration (cache directory is provided as a BuildKit cache mount below). +# CCACHE_MAXSIZE=2G keeps ccache's contribution to the GHA Actions Cache bounded. +# With Docker layer cache (~3-4 GB) plus ccache (<=2 GB), total stays comfortably +# under the 10 GB GHA per-repo cache quota. Do not raise beyond 4G without also +# verifying the layer cache footprint. +# CCACHE_COMPRESS=1 is redundant with ccache >=4.0 defaults but kept explicit for +# older-ccache compatibility (local builds on older distros). ENV CCACHE_DIR=/root/.ccache ENV CCACHE_MAXSIZE=2G ENV CCACHE_COMPRESS=1 @@ -14,8 +20,8 @@ ENV CCACHE_COMPRESS=1 # # IMPORTANT: the `rm -f /etc/apt/apt.conf.d/docker-clean` line is required. # Ubuntu/Debian base images ship an apt hook that auto-deletes -# /var/cache/apt/archives after every apt run, which silently defeats the -# BuildKit cache mount on /var/cache/apt. Do not remove this rm. +# /var/cache/apt/archives and /var/lib/apt/lists after every apt run, which +# silently defeats both BuildKit cache mounts below. Do not remove this rm. # # We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` # at the end, because those paths are mounted as BuildKit caches that we want @@ -73,7 +79,9 @@ COPY libraries $APPDIR/libraries # Dockerfiles so that production and testnet builds in the same workflow # benefit from each other's compiled-object cache. `make -j$(nproc) vizd` # (instead of unscoped `make`) skips cli_wallet, util programs, and tests -# that are not installed into the production image. +# that are not installed into the production image. `sharing=locked` is +# required because ccache is not concurrent-safe; `shared` would risk cache +# corruption under any future matrix-build setup. RUN --mount=type=cache,target=/root/.ccache,id=viz-ccache,sharing=locked \ cd $APPDIR && \ git submodule update --init --recursive -f && \ From 47dd3943e265b5011159168e22568ff74345972e Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 07:33:22 +0300 Subject: [PATCH 04/14] ci: add BuildKit cache mounts and scope make target in testnet Dockerfile Mirrors the changes to Dockerfile-production. Same cache mount IDs (viz-ccache for ccache, default for apt) so testnet and production builds in docker-main.yml share warm cache when run with the same GHA scope. Testnet-specific CMake flag (-DBUILD_TESTNET=TRUE) and runtime files (snapshot-testnet.json, config_testnet.ini) preserved verbatim. --- share/vizd/docker/Dockerfile-testnet | 48 ++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/share/vizd/docker/Dockerfile-testnet b/share/vizd/docker/Dockerfile-testnet index a9ebb23bad..a36c022671 100644 --- a/share/vizd/docker/Dockerfile-testnet +++ b/share/vizd/docker/Dockerfile-testnet @@ -1,10 +1,35 @@ +# syntax=docker/dockerfile:1.4 FROM phusion/baseimage:noble-1.0.3 AS builder ENV LANG=en_US.UTF-8 ENV APPDIR=/usr/local/src/viz/ ENV HOME=/var/lib/vizd -RUN \ +# ccache configuration (cache directory is provided as a BuildKit cache mount below). +# CCACHE_MAXSIZE=2G keeps ccache's contribution to the GHA Actions Cache bounded. +# With Docker layer cache (~3-4 GB) plus ccache (<=2 GB), total stays comfortably +# under the 10 GB GHA per-repo cache quota. Do not raise beyond 4G without also +# verifying the layer cache footprint. +# CCACHE_COMPRESS=1 is redundant with ccache >=4.0 defaults but kept explicit for +# older-ccache compatibility (local builds on older distros). +ENV CCACHE_DIR=/root/.ccache +ENV CCACHE_MAXSIZE=2G +ENV CCACHE_COMPRESS=1 + +# Install build dependencies. +# +# IMPORTANT: the `rm -f /etc/apt/apt.conf.d/docker-clean` line is required. +# Ubuntu/Debian base images ship an apt hook that auto-deletes +# /var/cache/apt/archives and /var/lib/apt/lists after every apt run, which +# silently defeats both BuildKit cache mounts below. Do not remove this rm. +# +# We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` +# at the end, because those paths are mounted as BuildKit caches that we want +# to persist across CI runs. The builder stage is discarded in the final image +# regardless, so leftover cache contents have no effect on the production image. +RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ + --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \ + rm -f /etc/apt/apt.conf.d/docker-clean && \ for i in 1 2 3; do \ apt-get update && \ apt-get install -y --no-install-recommends \ @@ -40,9 +65,7 @@ RUN \ pkg-config \ zlib1g-dev && \ break || sleep 10; \ - done && \ - apt-get clean && \ - rm -rf /var/lib/apt/lists/* + done # Explicitly copy needed files to avoid re-building when changing other files COPY .git $APPDIR/.git @@ -52,11 +75,18 @@ COPY thirdparty $APPDIR/thirdparty COPY plugins $APPDIR/plugins COPY libraries $APPDIR/libraries -RUN \ +# Build vizd. The named cache mount `viz-ccache` is shared across all VIZ +# Dockerfiles so that production and testnet builds in the same workflow +# benefit from each other's compiled-object cache. `make -j$(nproc) vizd` +# (instead of unscoped `make`) skips cli_wallet, util programs, and tests +# that are not installed into the final image. `sharing=locked` is +# required because ccache is not concurrent-safe; `shared` would risk cache +# corruption under any future matrix-build setup. +RUN --mount=type=cache,target=/root/.ccache,id=viz-ccache,sharing=locked \ cd $APPDIR && \ git submodule update --init --recursive -f && \ sed -i '/add_subdirectory(tests)/d' thirdparty/fc/CMakeLists.txt && \ - mkdir build && \ + mkdir -p build && \ cd build && \ cmake \ -DCMAKE_BUILD_TYPE=Release \ @@ -67,13 +97,17 @@ RUN \ -DENABLE_MONGO_PLUGIN=FALSE \ .. \ && \ - make -j$(nproc) + make -j$(nproc) vizd && \ + ccache -s RUN set -xe ;\ cd $APPDIR/build ;\ make install ;\ rm -rf $APPDIR +# Final cleanup of the builder stage. apt cache mounts above are not affected +# by these rm/clean calls because cache mounts are unmounted by the time this +# RUN executes; this only removes anything that landed in real layers. RUN \ apt-get clean && \ apt-get autoremove -y && \ From 9e8561d16f3ebfe07c3d39ef4bb154e3a64036b5 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 07:37:27 +0300 Subject: [PATCH 05/14] ci: align comment wording in testnet Dockerfile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror the line 82 'production image' → 'final image' wording fix into the apt-cache rationale comment block (line 29) so the testnet Dockerfile is internally consistent about the staging terminology. --- share/vizd/docker/Dockerfile-testnet | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/vizd/docker/Dockerfile-testnet b/share/vizd/docker/Dockerfile-testnet index a36c022671..f73a61f7d1 100644 --- a/share/vizd/docker/Dockerfile-testnet +++ b/share/vizd/docker/Dockerfile-testnet @@ -26,7 +26,7 @@ ENV CCACHE_COMPRESS=1 # We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` # at the end, because those paths are mounted as BuildKit caches that we want # to persist across CI runs. The builder stage is discarded in the final image -# regardless, so leftover cache contents have no effect on the production image. +# regardless, so leftover cache contents have no effect on the final image. RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \ rm -f /etc/apt/apt.conf.d/docker-clean && \ From eddc0624ed797267f268847efad422060e50d310 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 07:52:25 +0300 Subject: [PATCH 06/14] ci: enable GHA-backed BuildKit cache for PR Docker builds Adds docker/setup-buildx-action@v3 (required for advanced cache features) and cache-from/cache-to with type=gha,mode=max scoped per PR base branch. mode=max persists BuildKit cache mount contents (ccache, apt) across runs. Cache scope pr- means PRs against master share warm cache; PRs against release branches do not poison master's cache pool. --- .github/workflows/docker-pr-build.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.github/workflows/docker-pr-build.yml b/.github/workflows/docker-pr-build.yml index 9cbf383d4e..c7ea3b834c 100644 --- a/.github/workflows/docker-pr-build.yml +++ b/.github/workflows/docker-pr-build.yml @@ -16,14 +16,25 @@ jobs: with: submodules: recursive + # setup-buildx-action is required for advanced cache features + # (cache-from / cache-to with type=gha and mode=max). + - uses: docker/setup-buildx-action@v3 + - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} + # Cache scope is keyed on the PR's base branch so all PRs targeting + # master share one warm-cache pool, while PRs against release branches + # cannot poison master's cache. mode=max is required for BuildKit to + # also export the contents of named --mount=type=cache directories + # (notably /root/.ccache) across CI runs. - uses: docker/build-push-action@v6 with: context: . file: ./share/vizd/docker/Dockerfile-production push: true tags: vizblockchain/vizd:${{ github.head_ref }} + cache-from: type=gha,scope=pr-${{ github.event.pull_request.base_ref }} + cache-to: type=gha,scope=pr-${{ github.event.pull_request.base_ref }},mode=max From 78f54b563dd329083968b5e4435fc9d5278cf9a7 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:02:38 +0300 Subject: [PATCH 07/14] ci: enable shared GHA cache for master Docker builds Adds docker/setup-buildx-action@v3 and cache-from/cache-to (scope=main, mode=max) to both build_testnet and build_prod jobs. Same scope means build_prod inherits the warm ccache populated by build_testnet. Adds needs: build_testnet to build_prod so the two run sequentially and the cache-to export from testnet is available for prod's cache-from. Behavior change: a build_testnet failure now blocks build_prod (previously they were independent). --- .github/workflows/docker-main.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/workflows/docker-main.yml b/.github/workflows/docker-main.yml index 56c286a074..4cb70e6644 100644 --- a/.github/workflows/docker-main.yml +++ b/.github/workflows/docker-main.yml @@ -18,27 +18,42 @@ jobs: with: submodules: recursive + - uses: docker/setup-buildx-action@v3 + - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} + # Both jobs share scope=main so build_prod (which runs after + # build_testnet via needs:) can reuse the ccache populated by the + # testnet build. The two images differ only in CMake flags so most + # compiled object files have identical ccache hashes. - uses: docker/build-push-action@v6 with: context: . file: ./share/vizd/docker/Dockerfile-testnet push: true tags: vizblockchain/vizd:testnet + cache-from: type=gha,scope=main + cache-to: type=gha,scope=main,mode=max build_prod: name: Build production image runs-on: ubuntu-latest + # needs: build_testnet ensures build_prod runs after build_testnet so + # it can pull the warm cache exported by build_testnet's cache-to step. + # Side-effect: a build_testnet failure now blocks build_prod, which is + # arguably an improvement (don't ship prod if testnet is broken). + needs: build_testnet steps: - uses: actions/checkout@v4 with: submodules: recursive + - uses: docker/setup-buildx-action@v3 + - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USERNAME }} @@ -50,3 +65,5 @@ jobs: file: ./share/vizd/docker/Dockerfile-production push: true tags: vizblockchain/vizd:latest + cache-from: type=gha,scope=main + cache-to: type=gha,scope=main,mode=max From 1e622945f6bfc7f732d9b6858f2a089d39d86e17 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:05:46 +0300 Subject: [PATCH 08/14] ci: add manual cache-reset workflow for poisoned-cache recovery Implements the failure-mode mitigation #1 from the build-time spec. workflow_dispatch with a 'scope_substring' input that uses gh cache list/delete to remove all GHA cache entries whose key contains the substring. Common values: main, pr-master. Input is passed through an env: block (SCOPE_PATTERN) rather than direct ${{ inputs.* }} interpolation in the run: script, to close a workflow-injection vector that a single-quote-containing input could otherwise exploit. --- .github/workflows/cache-reset.yml | 52 +++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .github/workflows/cache-reset.yml diff --git a/.github/workflows/cache-reset.yml b/.github/workflows/cache-reset.yml new file mode 100644 index 0000000000..5c93ef21ea --- /dev/null +++ b/.github/workflows/cache-reset.yml @@ -0,0 +1,52 @@ +name: Reset CI Cache + +# Manual recovery for failure-mode #1 in +# docs/superpowers/specs/2026-04-28-ci-build-time-reduction-design.md: +# if a cache scope is poisoned (compile-time-only failures that warm +# builds reproduce but cold builds do not), run this workflow with the +# scope substring to delete all matching cache entries. +# +# Usage: GitHub UI -> Actions -> Reset CI Cache -> Run workflow +# Enter scope substring, e.g.: +# - "main" -> deletes master-branch cache +# - "pr-master" -> deletes shared PR-against-master cache +# - "pr-release-1.0" -> deletes a specific release-branch PR cache + +on: + workflow_dispatch: + inputs: + scope_substring: + description: 'Substring of cache key to delete (e.g., main, pr-master)' + required: true + type: string + +permissions: + actions: write # required to delete caches + +jobs: + reset: + runs-on: ubuntu-latest + steps: + - name: Delete matching caches + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Pass user input via env (not direct ${{ }} interpolation in the + # run: block) to avoid workflow-injection if the substring contains + # shell metacharacters like single quotes. + SCOPE_PATTERN: ${{ inputs.scope_substring }} + run: | + set -euo pipefail + echo "Listing caches matching: $SCOPE_PATTERN" + # gh cache list returns idkey... ; jq filters by key substring. + ids=$(gh cache list --repo "$GITHUB_REPOSITORY" --limit 100 --json id,key \ + | jq -r --arg pat "$SCOPE_PATTERN" '.[] | select(.key | contains($pat)) | .id') + if [ -z "$ids" ]; then + echo "No caches matched substring: $SCOPE_PATTERN" + exit 0 + fi + echo "Will delete cache IDs:" + echo "$ids" + echo "$ids" | while read -r id; do + gh cache delete "$id" --repo "$GITHUB_REPOSITORY" + done + echo "Done." From 25cc89bee8fc043618d700847155938539d5c927 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:10:13 +0300 Subject: [PATCH 09/14] ci: harden cache-reset workflow against partial cleanup and miscount Code-quality review of the initial cache-reset workflow flagged three issues, all fixed here: - --limit 100 could silently truncate the listing on busy repos. Raise to 1000 (gh CLI page max) and warn the operator if the listing hits the limit (signals possible incomplete cleanup). - set -e aborted the delete loop on the first gh cache delete failure (race with auto-eviction, transient 5xx). Switch to set -uo pipefail and best-effort deletes; track failure count and exit non-zero at the end so the GHA UI surfaces the partial-failure state. - jq contains() is substring-anywhere, so 'main' could match unrelated entries like 'domain-foo'. Echo idkey (not just id) before deleting so the operator can audit the match list in the run log. --- .github/workflows/cache-reset.yml | 43 ++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/.github/workflows/cache-reset.yml b/.github/workflows/cache-reset.yml index 5c93ef21ea..10db4fd2be 100644 --- a/.github/workflows/cache-reset.yml +++ b/.github/workflows/cache-reset.yml @@ -35,18 +35,41 @@ jobs: # shell metacharacters like single quotes. SCOPE_PATTERN: ${{ inputs.scope_substring }} run: | - set -euo pipefail + set -uo pipefail echo "Listing caches matching: $SCOPE_PATTERN" - # gh cache list returns idkey... ; jq filters by key substring. - ids=$(gh cache list --repo "$GITHUB_REPOSITORY" --limit 100 --json id,key \ - | jq -r --arg pat "$SCOPE_PATTERN" '.[] | select(.key | contains($pat)) | .id') - if [ -z "$ids" ]; then + # gh cache list returns idkey... ; jq filters by key + # substring. --limit 1000 is the gh CLI page max. If we hit the + # limit, the listing may be incomplete and the operator should + # rerun after the first batch is deleted. + LIMIT=1000 + listing=$(gh cache list --repo "$GITHUB_REPOSITORY" --limit "$LIMIT" --json id,key) + total=$(echo "$listing" | jq 'length') + if [ "$total" -eq "$LIMIT" ]; then + echo "WARN: hit --limit $LIMIT; listing may be truncated. Rerun after this batch." + fi + # Print idkey for each match so the operator can audit which + # entries are about to be deleted (substring matches can be broader + # than intended — e.g. 'main' matches 'domain-foo'). + matches=$(echo "$listing" \ + | jq -r --arg pat "$SCOPE_PATTERN" '.[] | select(.key | contains($pat)) | "\(.id)\t\(.key)"') + if [ -z "$matches" ]; then echo "No caches matched substring: $SCOPE_PATTERN" exit 0 fi - echo "Will delete cache IDs:" - echo "$ids" - echo "$ids" | while read -r id; do - gh cache delete "$id" --repo "$GITHUB_REPOSITORY" - done + echo "Will delete the following caches (idkey):" + echo "$matches" + # Best-effort deletion: a failure on one cache (race with auto- + # eviction, transient 5xx) should not abort the whole loop. + # Track failures and exit non-zero at the end if any occurred. + failures=0 + while IFS=$'\t' read -r id key; do + if ! gh cache delete "$id" --repo "$GITHUB_REPOSITORY"; then + echo "WARN: failed to delete cache id=$id key=$key" + failures=$((failures + 1)) + fi + done <<< "$matches" + if [ "$failures" -gt 0 ]; then + echo "Done with $failures failure(s)." + exit 1 + fi echo "Done." From 3324126271fe0a7b7d0f7ff4185f41296431cff5 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:16:25 +0300 Subject: [PATCH 10/14] ci: inline cache-reset failure-mode description Replaces the reference to docs/superpowers/specs/...-design.md (which is gitignored and not committed) with a self-contained description of when to use this workflow. External readers can now understand the recovery path without access to the local design spec. --- .github/workflows/cache-reset.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/workflows/cache-reset.yml b/.github/workflows/cache-reset.yml index 10db4fd2be..c5589e56b7 100644 --- a/.github/workflows/cache-reset.yml +++ b/.github/workflows/cache-reset.yml @@ -1,10 +1,9 @@ name: Reset CI Cache -# Manual recovery for failure-mode #1 in -# docs/superpowers/specs/2026-04-28-ci-build-time-reduction-design.md: -# if a cache scope is poisoned (compile-time-only failures that warm -# builds reproduce but cold builds do not), run this workflow with the -# scope substring to delete all matching cache entries. +# Manual recovery for poisoned BuildKit/ccache state: if a cache scope +# is producing compile-time-only failures that warm builds reproduce +# but cold builds do not, run this workflow with the scope substring +# to delete all matching cache entries and force a cold rebuild. # # Usage: GitHub UI -> Actions -> Reset CI Cache -> Run workflow # Enter scope substring, e.g.: From 1f7e30e71486e3304cb3a8770c8fe628fd449f33 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:27:54 +0300 Subject: [PATCH 11/14] chore: ignore local .claude/ directory Claude Code creates a .claude/ directory for per-project session and config state; it should not be tracked in the repo. --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 2eff007849..720ccd7c2f 100644 --- a/.gitignore +++ b/.gitignore @@ -52,4 +52,7 @@ documentation/doxygen/latex build # Local design specs and implementation plans (not part of repo) -docs/superpowers/ \ No newline at end of file +docs/superpowers/ + +# Claude Code local session/config files +.claude/ \ No newline at end of file From 4536425ef10a2871ffdd9a476f0e027cff41e0c5 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 08:29:03 +0300 Subject: [PATCH 12/14] ci: sanitize branch name into docker tag Docker tags cannot contain '/', but git branch names can (e.g. 'ci/build-time-reduction'). Replace direct ${{ github.head_ref }} interpolation with a sanitize step that uses bash parameter expansion (${BRANCH_NAME//\//-}) on a value passed via env: so the substitution can't be exploited as a workflow-injection vector. Pre-existing bug surfaced when a branch with '/' first hit the updated workflow. --- .github/workflows/docker-pr-build.yml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docker-pr-build.yml b/.github/workflows/docker-pr-build.yml index c7ea3b834c..8418c8470f 100644 --- a/.github/workflows/docker-pr-build.yml +++ b/.github/workflows/docker-pr-build.yml @@ -25,6 +25,18 @@ jobs: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} + # Docker tags cannot contain '/', but git branch names can (e.g. + # 'ci/build-time-reduction'). Sanitize via bash parameter expansion + # in an env-var (not direct ${{ }} interpolation) to avoid workflow + # injection if a branch name ever contains shell metacharacters. + - name: Compute docker tag from branch name + id: tag + env: + BRANCH_NAME: ${{ github.head_ref }} + run: | + set -euo pipefail + echo "value=${BRANCH_NAME//\//-}" >> "$GITHUB_OUTPUT" + # Cache scope is keyed on the PR's base branch so all PRs targeting # master share one warm-cache pool, while PRs against release branches # cannot poison master's cache. mode=max is required for BuildKit to @@ -35,6 +47,6 @@ jobs: context: . file: ./share/vizd/docker/Dockerfile-production push: true - tags: vizblockchain/vizd:${{ github.head_ref }} + tags: vizblockchain/vizd:${{ steps.tag.outputs.value }} cache-from: type=gha,scope=pr-${{ github.event.pull_request.base_ref }} cache-to: type=gha,scope=pr-${{ github.event.pull_request.base_ref }},mode=max From d16c676592487ae94bd8d2c546133fe71267bed7 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 09:50:06 +0300 Subject: [PATCH 13/14] ci: persist BuildKit cache mounts via buildkit-cache-dance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first measured warm-build rerun showed only ~6% improvement (15m57s cold, 14m56s warm) with ccache hit rate at 0/170 misses. Root cause: cache-from/cache-to type=gha,mode=max exports image LAYERS but NOT the contents of --mount=type=cache directories. On ephemeral GHA runners the BuildKit daemon is fresh each run, so named cache mounts (ccache, apt) start empty every time. Add the standard workaround: - actions/cache@v4 restores a host directory across runs. - reproducible-containers/buildkit-cache-dance@v3 binds it into BuildKit's cache mounts before build and extracts the post- build state for the next save. Cache key prefix is per-base-ref for PRs and 'main' for master, hashing both Dockerfiles so testnet/production share apt cache. Dockerfile change: explicitly enable Binary::apt::APT::Keep-Downloaded-Packages "true". Removing docker-clean is necessary but not sufficient — apt's own default deletes .deb files from /var/cache/apt/archives/ after install, which would leave the apt cache mount empty when extracted. --- .github/workflows/docker-main.yml | 60 +++++++++++++++++++++++++ .github/workflows/docker-pr-build.yml | 44 +++++++++++++++--- share/vizd/docker/Dockerfile-production | 7 +++ share/vizd/docker/Dockerfile-testnet | 7 +++ 4 files changed, 112 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docker-main.yml b/.github/workflows/docker-main.yml index 4cb70e6644..d098aaaef5 100644 --- a/.github/workflows/docker-main.yml +++ b/.github/workflows/docker-main.yml @@ -19,12 +19,42 @@ jobs: submodules: recursive - uses: docker/setup-buildx-action@v3 + id: setup-buildx - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} + # Cache-mount key hashes BOTH Dockerfiles so the testnet and + # production jobs (which install identical packages) compute the + # same key prefix — letting build_prod restore what build_testnet + # just saved. + - name: Restore BuildKit cache mounts from Actions Cache + uses: actions/cache@v4 + id: cache-mounts + with: + path: cache-mount + key: viz-cache-mount-${{ runner.os }}-main-${{ hashFiles('share/vizd/docker/Dockerfile-production', 'share/vizd/docker/Dockerfile-testnet') }}-${{ github.sha }} + restore-keys: | + viz-cache-mount-${{ runner.os }}-main-${{ hashFiles('share/vizd/docker/Dockerfile-production', 'share/vizd/docker/Dockerfile-testnet') }}- + viz-cache-mount-${{ runner.os }}-main- + + - name: Inject cache mounts into BuildKit + uses: reproducible-containers/buildkit-cache-dance@v3 + with: + builder: ${{ steps.setup-buildx.outputs.name }} + cache-map: | + { + "cache-mount/var-cache-apt": "/var/cache/apt", + "cache-mount/var-lib-apt-lists": "/var/lib/apt/lists", + "cache-mount/ccache": { + "target": "/root/.ccache", + "id": "viz-ccache" + } + } + skip-extraction: ${{ steps.cache-mounts.outputs.cache-hit }} + # Both jobs share scope=main so build_prod (which runs after # build_testnet via needs:) can reuse the ccache populated by the # testnet build. The two images differ only in CMake flags so most @@ -53,12 +83,42 @@ jobs: submodules: recursive - uses: docker/setup-buildx-action@v3 + id: setup-buildx - uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_PASSWORD }} + # Same cache-mount key prefix as build_testnet so this job restores + # the cache build_testnet just saved (same SHA, same Dockerfile + # hashes). Apt content fully reusable; ccache reuse depends on how + # -DBUILD_TESTNET propagates through the build (measured per run). + - name: Restore BuildKit cache mounts from Actions Cache + uses: actions/cache@v4 + id: cache-mounts + with: + path: cache-mount + key: viz-cache-mount-${{ runner.os }}-main-${{ hashFiles('share/vizd/docker/Dockerfile-production', 'share/vizd/docker/Dockerfile-testnet') }}-${{ github.sha }} + restore-keys: | + viz-cache-mount-${{ runner.os }}-main-${{ hashFiles('share/vizd/docker/Dockerfile-production', 'share/vizd/docker/Dockerfile-testnet') }}- + viz-cache-mount-${{ runner.os }}-main- + + - name: Inject cache mounts into BuildKit + uses: reproducible-containers/buildkit-cache-dance@v3 + with: + builder: ${{ steps.setup-buildx.outputs.name }} + cache-map: | + { + "cache-mount/var-cache-apt": "/var/cache/apt", + "cache-mount/var-lib-apt-lists": "/var/lib/apt/lists", + "cache-mount/ccache": { + "target": "/root/.ccache", + "id": "viz-ccache" + } + } + skip-extraction: ${{ steps.cache-mounts.outputs.cache-hit }} + - uses: docker/build-push-action@v6 with: context: . diff --git a/.github/workflows/docker-pr-build.yml b/.github/workflows/docker-pr-build.yml index 8418c8470f..9c80ca752a 100644 --- a/.github/workflows/docker-pr-build.yml +++ b/.github/workflows/docker-pr-build.yml @@ -17,8 +17,10 @@ jobs: submodules: recursive # setup-buildx-action is required for advanced cache features - # (cache-from / cache-to with type=gha and mode=max). + # (cache-from / cache-to with type=gha and mode=max). The id: lets + # buildkit-cache-dance below pick up the builder name. - uses: docker/setup-buildx-action@v3 + id: setup-buildx - uses: docker/login-action@v3 with: @@ -37,11 +39,41 @@ jobs: set -euo pipefail echo "value=${BRANCH_NAME//\//-}" >> "$GITHUB_OUTPUT" - # Cache scope is keyed on the PR's base branch so all PRs targeting - # master share one warm-cache pool, while PRs against release branches - # cannot poison master's cache. mode=max is required for BuildKit to - # also export the contents of named --mount=type=cache directories - # (notably /root/.ccache) across CI runs. + # cache-from/cache-to type=gha exports Docker LAYERS but not the + # contents of --mount=type=cache directories (ccache, apt). On + # ephemeral GHA runners the BuildKit daemon is fresh each run, so + # named cache mounts always start empty without the dance below. + # actions/cache restores a host directory across runs; + # buildkit-cache-dance binds it into the build's cache mounts and + # extracts the post-build state for the next save. + - name: Restore BuildKit cache mounts from Actions Cache + uses: actions/cache@v4 + id: cache-mounts + with: + path: cache-mount + key: viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}-${{ github.sha }} + restore-keys: | + viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}- + viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}- + + - name: Inject cache mounts into BuildKit + uses: reproducible-containers/buildkit-cache-dance@v3 + with: + builder: ${{ steps.setup-buildx.outputs.name }} + cache-map: | + { + "cache-mount/var-cache-apt": "/var/cache/apt", + "cache-mount/var-lib-apt-lists": "/var/lib/apt/lists", + "cache-mount/ccache": { + "target": "/root/.ccache", + "id": "viz-ccache" + } + } + skip-extraction: ${{ steps.cache-mounts.outputs.cache-hit }} + + # Layer cache scope is keyed on the PR's base branch so all PRs + # targeting master share one warm-cache pool, while PRs against + # release branches cannot poison master's cache. - uses: docker/build-push-action@v6 with: context: . diff --git a/share/vizd/docker/Dockerfile-production b/share/vizd/docker/Dockerfile-production index ec4cc8e427..9021b9196e 100644 --- a/share/vizd/docker/Dockerfile-production +++ b/share/vizd/docker/Dockerfile-production @@ -23,6 +23,12 @@ ENV CCACHE_COMPRESS=1 # /var/cache/apt/archives and /var/lib/apt/lists after every apt run, which # silently defeats both BuildKit cache mounts below. Do not remove this rm. # +# Equally important: the Keep-Downloaded-Packages line. Even with +# docker-clean removed, apt's default is to delete .deb archives after +# install (Binary::apt::APT::Keep-Downloaded-Packages "false"). Without +# explicitly flipping it to "true", buildkit-cache-dance extracts an +# empty /var/cache/apt/archives/ from the cache mount. +# # We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` # at the end, because those paths are mounted as BuildKit caches that we want # to persist across CI runs. The builder stage is discarded in the final image @@ -30,6 +36,7 @@ ENV CCACHE_COMPRESS=1 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \ rm -f /etc/apt/apt.conf.d/docker-clean && \ + echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' >/etc/apt/apt.conf.d/keep-cache && \ for i in 1 2 3; do \ apt-get update && \ apt-get install -y --no-install-recommends \ diff --git a/share/vizd/docker/Dockerfile-testnet b/share/vizd/docker/Dockerfile-testnet index f73a61f7d1..e1601de7fd 100644 --- a/share/vizd/docker/Dockerfile-testnet +++ b/share/vizd/docker/Dockerfile-testnet @@ -23,6 +23,12 @@ ENV CCACHE_COMPRESS=1 # /var/cache/apt/archives and /var/lib/apt/lists after every apt run, which # silently defeats both BuildKit cache mounts below. Do not remove this rm. # +# Equally important: the Keep-Downloaded-Packages line. Even with +# docker-clean removed, apt's default is to delete .deb archives after +# install (Binary::apt::APT::Keep-Downloaded-Packages "false"). Without +# explicitly flipping it to "true", buildkit-cache-dance extracts an +# empty /var/cache/apt/archives/ from the cache mount. +# # We also intentionally do NOT run `apt-get clean` or `rm -rf /var/lib/apt/lists/*` # at the end, because those paths are mounted as BuildKit caches that we want # to persist across CI runs. The builder stage is discarded in the final image @@ -30,6 +36,7 @@ ENV CCACHE_COMPRESS=1 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \ rm -f /etc/apt/apt.conf.d/docker-clean && \ + echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' >/etc/apt/apt.conf.d/keep-cache && \ for i in 1 2 3; do \ apt-get update && \ apt-get install -y --no-install-recommends \ From 0a1765410aa1f95271174910fc6bcd29799c1e88 Mon Sep 17 00:00:00 2001 From: Vladimir Babin Date: Tue, 28 Apr 2026 10:59:22 +0300 Subject: [PATCH 14/14] fix(ci): correct base-branch field in PR cache scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `github.event.pull_request.base_ref` is not a real field on the pull_request event — it silently resolves to empty string. Switching to `github.base_ref` (the documented top-level shortcut) restores the intended cache-pool segregation: PRs against `master` share one warm pool, PRs against release branches get their own. Without this fix, all PRs shared a single `pr-` pool regardless of base branch — functionally fine for cache reuse, but loses the isolation property that prevents a PR against a release branch from poisoning master's pool. Side effect: the rename invalidates the existing warm cache on this branch (key segment changes from empty to "master"). Next push will be cold; subsequent reruns warm under the corrected key. --- .github/workflows/docker-pr-build.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docker-pr-build.yml b/.github/workflows/docker-pr-build.yml index 9c80ca752a..ac982b0508 100644 --- a/.github/workflows/docker-pr-build.yml +++ b/.github/workflows/docker-pr-build.yml @@ -51,10 +51,10 @@ jobs: id: cache-mounts with: path: cache-mount - key: viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}-${{ github.sha }} + key: viz-cache-mount-${{ runner.os }}-pr-${{ github.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}-${{ github.sha }} restore-keys: | - viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}- - viz-cache-mount-${{ runner.os }}-pr-${{ github.event.pull_request.base_ref }}- + viz-cache-mount-${{ runner.os }}-pr-${{ github.base_ref }}-${{ hashFiles('share/vizd/docker/Dockerfile-production') }}- + viz-cache-mount-${{ runner.os }}-pr-${{ github.base_ref }}- - name: Inject cache mounts into BuildKit uses: reproducible-containers/buildkit-cache-dance@v3 @@ -80,5 +80,5 @@ jobs: file: ./share/vizd/docker/Dockerfile-production push: true tags: vizblockchain/vizd:${{ steps.tag.outputs.value }} - cache-from: type=gha,scope=pr-${{ github.event.pull_request.base_ref }} - cache-to: type=gha,scope=pr-${{ github.event.pull_request.base_ref }},mode=max + cache-from: type=gha,scope=pr-${{ github.base_ref }} + cache-to: type=gha,scope=pr-${{ github.base_ref }},mode=max