From a964a3808bdd6047aa99dd069d83d8ce8ef983bf Mon Sep 17 00:00:00 2001
From: Nathan Gillett <nathan@intentproof.io>
Date: Sat, 30 May 2026 18:21:13 -0500
Subject: [PATCH] Add SOURCE_REF and CI check for tuple bookkeeping

Fail CI when HEAD diverges from SOURCE_REF so spec pins/matrix
can record the SDK commit in the ecosystem tuple.
---
 scripts/check-source-ref.sh | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100755 scripts/check-source-ref.sh

diff --git a/scripts/check-source-ref.sh b/scripts/check-source-ref.sh
new file mode 100755
index 0000000..1ac3110
--- /dev/null
+++ b/scripts/check-source-ref.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Fail when SOURCE_REF does not match the current commit (tuple bookkeeping).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+if [[ ! -f SOURCE_REF ]]; then
+  echo "SKIP: SOURCE_REF not present yet (add when bumping the ecosystem tuple)."
+  exit 0
+fi
+
+HEAD="$(git rev-parse HEAD)"
+REF="$(tr -d '[:space:]' < SOURCE_REF)"
+if ! echo "$REF" | grep -qE '^[0-9a-f]{40}$'; then
+  echo "Invalid SOURCE_REF: must be a 40-character lowercase git SHA" >&2
+  exit 1
+fi
+
+if [[ "$HEAD" == "$REF" ]]; then
+  echo "PASS: SOURCE_REF matches HEAD ($HEAD)."
+  exit 0
+fi
+
+if git merge-base --is-ancestor "$REF" "$HEAD" 2>/dev/null; then
+  echo "FAIL: HEAD ($HEAD) is ahead of SOURCE_REF ($REF)" >&2
+  echo "Bump SOURCE_REF to HEAD and update spec pins/matrix for the tuple." >&2
+  exit 1
+fi
+
+echo "FAIL: SOURCE_REF ($REF) is not an ancestor of HEAD ($HEAD)" >&2
+exit 1