ci(adcp-sdk): pin @adcp/sdk to 7.10.1, salt cache key with version

@adcp/sdk@latest was floating, and the npm cache key
``${{ runner.os }}-npm-adcp-sdk`` was OS-only — so a runner that cached
an older release served stale SDK to every subsequent CI run on that
runner, while a fresh runner pulled the current @latest. Same commit
flipped red/green depending on which runner picked it up (see 2026-05-21
storyboard incident, adcp#4907).

- ADCP_SDK_VERSION env var pinned at workflow header (7.10.1).
- All 4 ``npm install -g @adcp/sdk@latest`` sites use the pin.
- All 4 cache keys salted with ${{ env.ADCP_SDK_VERSION }} so a bump
  invalidates deterministically.
- Stale comments rationalizing @latest removed.

Bumping the SDK version now happens via PR — silent-upgrade footgun
closed. Tracks adcp-client-python#779 Track B and adcp#4907 Phase 1.

Author: bokelley

.github/workflows/ci.yml

@@ -6,6 +6,11 @@ on:
   pull_request:
     branches: [main]
 
+# Pinned @adcp/sdk version. Bump deliberately; cache invalidates when this moves.
+# Background: adcontextprotocol/adcp-client-python#779 (Track B), adcontextprotocol/adcp#4907.
+env:
+  ADCP_SDK_VERSION: "7.9.0"
+
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
@@ -369,28 +374,23 @@ jobs:
 
       # Cache the npm tarball + extracted package directory so the
       # storyboard runner install isn't a cold network fetch every run.
-      # Key by OS only (not by version) so the cache survives across
-      # ``@adcp/sdk`` releases — npm install reuses tarballs that are
-      # already in the cache and only fetches the delta. ``@latest`` is
-      # intentional for drift detection (see "Run storyboard suite"
-      # below); the cache amortizes the 5-15 s of fetch+extract that
-      # would otherwise repeat on every CI run.
+      # Cache key is salted with the pinned ``@adcp/sdk`` version so
+      # bumping ADCP_SDK_VERSION invalidates the cache deterministically.
       - name: Cache ~/.npm
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-npm-adcp-sdk
+          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
           restore-keys: |
             ${{ runner.os }}-npm-
 
       - name: Pre-install @adcp/sdk (once, then call binary directly)
         # Single install step at the top of the job; subsequent runner
         # calls invoke the already-installed binary instead of paying
         # the ``npx -y -p ...`` per-invocation extract+link tax.
-        # ``@adcp/sdk@latest`` is intentionally unpinned: this is AdCP's
-        # own CI running AdCP's own canonical runner — tracking latest
-        # surfaces protocol drift as soon as it ships, which is the
-        # point of this job.
+        # Pinned to ADCP_SDK_VERSION (see workflow header) — bump via PR
+        # so reference-impl breakage from a new SDK release shows up as
+        # a labelled change set, not silent CI flake.
         #
         # Vendor missing fixtures into the SDK install:
         # ``@adcp/sdk`` does not ship two fixtures its storyboard runner
@@ -403,13 +403,18 @@ jobs:
         # into the SDK's expected locations post-install; idempotent if
         # upstream later ships them in the npm tarball.
         run: |
-          npm install -g @adcp/sdk@latest
+          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
           adcp --version
           SDK_ROOT="$(npm root -g)/@adcp/sdk"
           mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
           cp tests/fixtures/aao-reference-formats.json "${SDK_ROOT}/test/lib/v2-projection-fixtures/aao-reference-formats.json"
           mkdir -p "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries"
           cp tests/fixtures/v1-canonical-mapping.json "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries/v1-canonical-mapping.json"
+          SDK_ROOT="$(npm root -g)/@adcp/sdk"
+          mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
+          cp tests/fixtures/aao-reference-formats.json "${SDK_ROOT}/test/lib/v2-projection-fixtures/aao-reference-formats.json"
+          mkdir -p "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries"
+          cp tests/fixtures/v1-canonical-mapping.json "${SDK_ROOT}/schemas/cache/3.1.0-beta.2/registries/v1-canonical-mapping.json"
 
       - name: Install dependencies
         run: |
@@ -541,15 +546,13 @@ jobs:
         with:
           node-version: "22"
 
-      # Cache ~/.npm by OS only so subsequent runs hit the tarball
-      # cache; npm install reuses what's there and only fetches the
-      # delta on a new ``@latest`` release. See the storyboard job
-      # above for the same pattern + rationale.
+      # Same cache pattern as the storyboard job: keyed by
+      # ADCP_SDK_VERSION so a bump invalidates deterministically.
       - name: Cache ~/.npm
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-npm-adcp-sdk
+          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
           restore-keys: |
             ${{ runner.os }}-npm-
 
@@ -567,7 +570,7 @@ jobs:
         # See the comment on the storyboard job's install step for the
         # AAO reference-formats fixture rationale (upstream adcp#3307).
         run: |
-          npm install -g @adcp/sdk@latest
+          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
           adcp --version
           SDK_ROOT="$(npm root -g)/@adcp/sdk"
           mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
@@ -775,15 +778,15 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-npm-adcp-sdk
+          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
           restore-keys: |
             ${{ runner.os }}-npm-
 
       - name: Pre-install @adcp/sdk
         # See the comment on the storyboard job's install step for the
         # AAO reference-formats fixture rationale (upstream adcp#3307).
         run: |
-          npm install -g @adcp/sdk@latest
+          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
           adcp --version
           SDK_ROOT="$(npm root -g)/@adcp/sdk"
           mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"
@@ -883,15 +886,15 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: ${{ runner.os }}-npm-adcp-sdk
+          key: ${{ runner.os }}-npm-adcp-sdk-${{ env.ADCP_SDK_VERSION }}
           restore-keys: |
             ${{ runner.os }}-npm-
 
       - name: Pre-install @adcp/sdk
         # See the comment on the storyboard job's install step for the
         # AAO reference-formats fixture rationale (upstream adcp#3307).
         run: |
-          npm install -g @adcp/sdk@latest
+          npm install -g @adcp/sdk@${ADCP_SDK_VERSION}
           adcp --version
           SDK_ROOT="$(npm root -g)/@adcp/sdk"
           mkdir -p "${SDK_ROOT}/test/lib/v2-projection-fixtures"