fix(deps): split BD_VERSION into version + source ref (ga-kgluj)

.github/scripts/install-bd-archive.sh

@@ -38,13 +38,24 @@ while (($#)); do
   shift
 done
 
-# A 40-hex VERSION is a beads commit: no release tarball exists for it, so bd
-# is built from source at that commit. The commit hash itself pins the exact
-# source tree (git content addressing), standing in for the tarball SHA-256
-# pin of the release path.
+# Which commit to build, if any.
+#
+# BD_SOURCE_REF (optional) builds bd from that commit while VERSION stays a real
+# version string. deps.env used to conflate the two — it put a commit SHA in
+# BD_VERSION — which forced every consumer to treat a version field as a ref.
+# Splitting them mirrors contrib/k8s/Dockerfile.agent's existing ARG model.
+#
+# A 40-hex VERSION is still honoured for backwards compatibility: no release
+# tarball exists for it, so bd is built from source at that commit. The commit
+# hash pins the exact source tree (git content addressing), standing in for the
+# tarball SHA-256 pin of the release path.
+source_ref="${BD_SOURCE_REF:-}"
 build_from_source=false
-if [[ "$version" =~ ^[0-9a-f]{40}$ ]]; then
+if [[ -n "$source_ref" ]]; then
   build_from_source=true
+elif [[ "$version" =~ ^[0-9a-f]{40}$ ]]; then
+  build_from_source=true
+  source_ref="$version"
 fi
 
 case "$(uname -s)" in
@@ -152,7 +163,12 @@ install_binary_with_sudo_fallback() {
 
 if $use_cache; then
   cache_root="${RUNNER_TOOL_CACHE:-$HOME/.local}"
-  bin_dir="${cache_root}/gascity-bd/${version}/${platform_tuple}/bin"
+  # Include the source ref in the cache key: with VERSION now a real version
+  # string, a cached RELEASE build of v1.1.0 must never be reused for a
+  # source-pinned build of the same version.
+  cache_slug="${version}"
+  if [[ -n "$source_ref" ]]; then cache_slug="${version}-src-${source_ref:0:12}"; fi
+  bin_dir="${cache_root}/gascity-bd/${cache_slug}/${platform_tuple}/bin"
 else
   bin_dir="${BD_INSTALL_BIN_DIR:-/usr/local/bin}"
 fi
@@ -162,13 +178,13 @@ if [[ -x "$target" ]]; then
   echo "Reusing cached bd ${version} at ${target}"
 elif $build_from_source; then
   if ! command -v go >/dev/null 2>&1; then
-    echo "go is required to build bd from source at commit ${version}" >&2
+    echo "go is required to build bd from source at commit ${source_ref}" >&2
     exit 1
   fi
   tmp="$(mktemp -d)"
   trap 'rm -rf "$tmp"' EXIT
   git clone --filter=blob:none https://github.com/gastownhall/beads "${tmp}/beads-src"
-  git -C "${tmp}/beads-src" checkout "$version"
+  git -C "${tmp}/beads-src" checkout "$source_ref"
   # Same build shape as ci.yml's cross-version contract cells.
   go -C "${tmp}/beads-src" build -tags gms_pure_go -o "${tmp}/bd" ./cmd/bd
   if $use_cache; then

.github/workflows/ci.yml

@@ -271,7 +271,8 @@ jobs:
     runs-on: ${{ needs.runner-policy.outputs.runner_32vcpu }}
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ./.github/actions/setup-gascity-ubuntu
@@ -300,7 +301,8 @@ jobs:
     runs-on: ${{ needs.runner-policy.outputs.runner_32vcpu }}
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     strategy:
       fail-fast: false
       matrix:
@@ -560,7 +562,8 @@ jobs:
         shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ./.github/actions/setup-gascity-ubuntu
@@ -714,7 +717,8 @@ jobs:
             command: ./scripts/test-integration-shard rest-smoke-2-of-2
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ./.github/actions/setup-gascity-ubuntu
@@ -741,7 +745,8 @@ jobs:
         shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ./.github/actions/setup-gascity-ubuntu

.github/workflows/fork-verify.yml

@@ -27,7 +27,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ./.github/actions/setup-gascity-ubuntu

.github/workflows/mac-regression.yml

@@ -75,7 +75,8 @@ concurrency:
 
 env:
   DOLT_VERSION: "2.1.7"
-  BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+  BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+  BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
 
 # Trigger gate re-used by every job below via `if:`.
 # We want each job to run when EITHER:

.github/workflows/nightly.yml

@@ -10,7 +10,8 @@ permissions:
 
 env:
   DOLT_VERSION: "2.1.7"
-  BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+  BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+  BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
 
 jobs:
   tier-b:
@@ -89,7 +90,8 @@ jobs:
     timeout-minutes: 30
     env:
       DOLT_VERSION: "2.1.7"
-      BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+      BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+      BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
       GC_BEADS: sqlite
       GC_ACCEPTANCE_BEADS_PROVIDER: sqlite
     steps:

.github/workflows/ollama-acceptance-c.yml

@@ -8,7 +8,8 @@ permissions:
 
 env:
   DOLT_VERSION: "2.1.7"
-  BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+  BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+  BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
   ANTHROPIC_BASE_URL: https://ollama.com
   ANTHROPIC_API_KEY: ""
   ANTHROPIC_AUTH_TOKEN: ${{ secrets.OLLAMA_API_KEY }}

.github/workflows/rc-gate.yml

@@ -8,7 +8,8 @@ permissions:
 
 env:
   DOLT_VERSION: "2.1.7"
-  BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+  BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+  BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
   # Bypass the systemd gascity-test.slice re-exec on CI runners. The Blacksmith
   # runners' user systemd cannot reliably create a transient --scope for the
   # heavy acceptance workloads; gc_test_slice_reexec then exec's

.github/workflows/review-formulas.yml

@@ -37,7 +37,8 @@ concurrency:
 
 env:
   DOLT_VERSION: "2.1.7"
-  BD_VERSION: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054; lockstep with go.mod beads pin (deps.env, vp-kpoi)
+  BD_VERSION: "v1.1.0" # version string; source commit in BD_SOURCE_REF (lockstep with go.mod beads pin; deps.env, vp-kpoi)
+  BD_SOURCE_REF: "e97839a2e1c0de305bf64a01b997f2f314591aa4" # bd commit with schema 0054 — built from source by install-bd-archive.sh
 
 jobs:
   runner-policy:

contrib/k8s/Dockerfile.agent

@@ -19,10 +19,16 @@ ARG BASE_IMAGE=gc-agent-base:latest
 
 FROM golang:1.26.5-bookworm@sha256:1ecb7edf62a0408027bd5729dfd6b1b8766e578e8df93995b225dfd0944eb651 AS bd-builder
 
+# TIME-BOXED BRIDGE (ADR-0026 C5, vp-kpoi) — keep in lockstep with deps.env.
+# BD_VERSION is the version string the pinned source declares; BD_SOURCE_REF is
+# the commit built from. Upstream's ref (8e4e59d39) tops out at schema migration
+# 0053, but gc's linked beads library carries 0054, so a 0053 bd in this image
+# would skew from the linked lib. Repointed at the same commit go.mod pins.
+# Revert all three to upstream's values once a release carries 0054.
 ARG BD_VERSION=v1.1.0
-ARG BD_SOURCE_REF=8e4e59d39f3459a43cf21a3236a13eca4dd874f7
-ARG BD_SOURCE_SHA256=63597b6b368d7d26ba3fc570ae3b2fa4cd8a5155d4716cae13d178a560808d5a
-ARG BD_BUILD=8e4e59d39
+ARG BD_SOURCE_REF=e97839a2e1c0de305bf64a01b997f2f314591aa4
+ARG BD_SOURCE_SHA256=e40acdcbca7bdc08b986113692e11be7a533b9fced326c20e786f141c29996f1
+ARG BD_BUILD=e97839a2e
 ARG BD_BRANCH=HEAD
 ARG GRPC_VERSION=1.82.1
 

deps.env

@@ -6,15 +6,28 @@
 
 DOLT_VERSION=2.1.7
 BD_REPO=gastownhall/beads
-# BD_VERSION is the bd binary CI and images run alongside gc. TIME-BOXED
-# BRIDGE (ADR-0026 C5, vp-kpoi): pinned to a gastownhall/beads COMMIT — built
-# from source by .github/scripts/install-bd-archive.sh — because gc's linked
-# beads library (go.mod: v1.1.1-0.20260704062855-e97839a2e1c0, same commit)
-# carries schema migration 0054 while the newest bd release (v1.1.0) tops out
-# at 0053; a released bd would skew from the linked lib and break the
-# raw-bd/gc-bd/provider-store consistency contract. When upstream cuts a
-# release >= 0054, repin this and go.mod to that tag in ONE change.
-BD_VERSION=e97839a2e1c0de305bf64a01b997f2f314591aa4
+# BD_VERSION is the bd binary CI and images run alongside gc — the VERSION
+# STRING, matching what cmd/bd/version.go declares in the pinned source. It is
+# asserted and stamped by contrib/k8s/Dockerfile.agent.
+#
+# BD_SOURCE_REF is WHICH COMMIT that binary is built from. TIME-BOXED BRIDGE
+# (ADR-0026 C5, vp-kpoi): gc's linked beads library (go.mod:
+# v1.1.1-0.20260704062855-e97839a2e1c0, the same commit) carries schema
+# migration 0054, while every published bd release — including v1.1.2 — tops
+# out at 0053. A released bd would skew from the linked lib and break the
+# raw-bd/gc-bd/provider-store consistency contract.
+#
+# These are two different things and were previously conflated: BD_VERSION held
+# a commit SHA, which is not a version. Splitting them mirrors the ARG model
+# contrib/k8s/Dockerfile.agent already uses (BD_VERSION + BD_SOURCE_REF +
+# BD_SOURCE_SHA256), so the pin no longer has to lie about its own version.
+#
+# The pinned commit declares Version = "1.1.0", hence BD_VERSION=v1.1.0.
+# When upstream cuts a release >= 0054: set BD_VERSION to that tag, delete
+# BD_SOURCE_REF/BD_SOURCE_SHA256, and repin go.mod — in ONE change.
+BD_VERSION=v1.1.0
+BD_SOURCE_REF=e97839a2e1c0de305bf64a01b997f2f314591aa4
+BD_SOURCE_SHA256=e40acdcbca7bdc08b986113692e11be7a533b9fced326c20e786f141c29996f1
 BR_VERSION=0.1.20
 
 # Cross-version contract-test matrix pins.

scripts/bd_version_pin_test.go

@@ -36,6 +36,7 @@
 	bdPrev := env["BD_PREV_VERSION"]       // min-supported matrix cell (downloadable)
 	bdCurrent := env["BD_CURRENT_VERSION"] // bleeding-edge matrix cell (built from source)
 	bdCurrentRef := env["BD_CURRENT_REF"]  // beads commit the current cell builds from
+	bdSourceRef := env["BD_SOURCE_REF"]    // beads commit the installable default builds from (bridge mode)
 
 	if bdVersion == "" {
 		t.Fatal("deps.env missing BD_VERSION")
@@ -57,9 +58,20 @@
 		t.Fatalf("deps.env BD_CURRENT_VERSION = %q, want a semver token", bdCurrent)
 	}
 
-	// Bridge-mode detection: a 40-hex BD_VERSION pins a beads commit built from
-	// source instead of a release tarball.
-	bdVersionIsCommit := regexp.MustCompile(`^[0-9a-f]{40}$`).MatchString(bdVersion)
+	// Bridge-mode detection. The installable default is built from source when
+	// deps.env carries BD_SOURCE_REF — the version/ref split that mirrors the
+	// BD_CURRENT_VERSION/BD_CURRENT_REF pair above, so BD_VERSION can stay a real
+	// version string instead of holding a commit SHA. A 40-hex BD_VERSION is the
+	// legacy spelling of the same thing and is still honoured.
+	commitRE := regexp.MustCompile(`^[0-9a-f]{40}$`)
+	bridgeRef := bdSourceRef
+	if bridgeRef == "" && commitRE.MatchString(bdVersion) {
+		bridgeRef = bdVersion
+	}
+	if bdSourceRef != "" && !commitRE.MatchString(bdSourceRef) {
+		t.Fatalf("deps.env BD_SOURCE_REF = %q, want a full 40-char gastownhall/beads commit SHA", bdSourceRef)
+	}
+	bdVersionIsCommit := bridgeRef != ""
 
 	// Lockstep with the linked library. The bd binary CI installs and the beads
 	// library gc links must carry the same schema-migration level: a go.mod
@@ -78,11 +90,11 @@
 	pseudo := regexp.MustCompile(`[-.]\d{14}-([0-9a-f]{12})$`).FindStringSubmatch(linkedBeads)
 	switch {
 	case bdVersionIsCommit && pseudo == nil:
-		t.Fatalf("deps.env BD_VERSION pins beads commit %s but go.mod links released beads %s; the bd binary and the linked library must move together", bdVersion, linkedBeads)
-	case bdVersionIsCommit && !strings.HasPrefix(bdVersion, pseudo[1]):
-		t.Fatalf("deps.env BD_VERSION = %s but go.mod's beads pseudo-version %s pins commit %s; the bd binary and the linked library must pin the SAME beads commit", bdVersion, linkedBeads, pseudo[1])
+		t.Fatalf("deps.env pins beads commit %s but go.mod links released beads %s; the bd binary and the linked library must move together", bridgeRef, linkedBeads)
+	case bdVersionIsCommit && !strings.HasPrefix(bridgeRef, pseudo[1]):
+		t.Fatalf("deps.env pins beads commit %s but go.mod's beads pseudo-version %s pins commit %s; the bd binary and the linked library must pin the SAME beads commit", bridgeRef, linkedBeads, pseudo[1])
 	case !bdVersionIsCommit && pseudo != nil:
-		t.Fatalf("go.mod links untagged beads commit %s (%s) but deps.env BD_VERSION = %s installs a release; pin BD_VERSION to the same commit, or move go.mod to a release tag", pseudo[1], linkedBeads, bdVersion)
+		t.Fatalf("go.mod links untagged beads commit %s (%s) but deps.env installs release %s; set BD_SOURCE_REF to the same commit, or move go.mod to a release tag", pseudo[1], linkedBeads, bdVersion)
 	}
 
 	// Anchor roles, kept as distinct contracts so a promotion cannot quietly

scripts/cipolicy/policy.go

@@ -25,13 +25,17 @@
 	// auto-merged both sides' changes, so the resulting shape hashes to neither
 	// the fork's nor upstream's previous value — the correct action is to
 	// re-derive from the merged workflow rather than adopt either side's stale pin.
-	expectedCIExecutionHash     = "d316ebebefe2505a5e17d8d849c7c7adc74dc457f79cd24f7a5033858075a408"
+	// Re-derived again for ga-kgluj: splitting BD_VERSION into BD_VERSION +
+	// BD_SOURCE_REF adds a job-level env key, and env is part of the execution
+	// shape this pin guards — so the tripwire firing here is correct behaviour,
+	// not noise.
+	expectedCIExecutionHash     = "41d38414857d74ccb3d7faffe10deb0c27e92aaf87bfeafb94351bacf7ffe1b7"
 	expectedNightlyTriggersHash = "0a4400a09ac567e90adf8be1232eef1f14e36efd8dba3e143aa6e36f5b7a36f5"
 	// Re-derived like the CI pin above. Note this one lands on the FORK's prior
 	// value: nightly.yml merged to the fork's execution shape, so wholesale
 	// --theirs on this file would have adopted upstream's pin and failed. Each
 	// pin is an independent tripwire and must be re-derived on its own.
-	expectedNightlyExecutionHash = "79c17c6febb370f371c80fc09c9e6d73b5c7ff8da891a23691dbdc60b3050d75"
+	expectedNightlyExecutionHash = "383509972a3f0c73b6d5653040de042b4d183a650cc32a0a4c14439899a97d5d"
 	expectedSetupActionHash      = "b7864038195cd054aee7fccfa903cab335b375bcab1a35239c17c5da7d32c07e"
 )