From cc097868ab0b865d1fc4eca94fa3185c22ca18b2 Mon Sep 17 00:00:00 2001
From: Arturo Peroni <arturo@tracebloc.io>
Date: Thu, 27 Aug 2026 16:44:51 +0200
Subject: [PATCH 1/2] fix(sync): watch the data-ingestors pin for
 contract-version drift (backend#2704)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`scripts/sync-schema.sh --check` verifies the vendored contract matches the
PINNED SHA — it answers "does my copy match what I pinned?", never "is what I
pinned still current?". So the pin silently went a whole contract VERSION behind
(layout v2 vs data-ingestors@develop v3, di#535) while every drift gate stayed
green. The pin is deliberate and stays (backend#1009: a floating ref reds every
open CLI PR on unrelated upstream commits).

Add a watcher for the pin itself:

- scripts/check-pin-version.sh resolves the pin and data-ingestors' current
  default branch, fetches layout.v1.json at both, and compares the top-level
  "version" — VERSION, not commit distance (180 unrelated commits are fine).
  FAILS CLOSED: absent/malformed pin, moved path, unreachable raw URL, non-JSON,
  or missing "version" all exit non-zero. Exit 0 in sync, 1 drift, 2 can't-eval.
- .github/workflows/pin-version-drift.yml runs it weekly (Mon 06:30 UTC, after
  head-drift-canary) + workflow_dispatch. No pull_request trigger — gating PRs
  on live upstream is the backend#1009 failure. The pinned PR comparison is
  unchanged.
- scripts/tests/pin-version-verify.sh mutation-proves it hermetically (drift
  reddens; each cannot-evaluate reddens), wired into build.yml alongside the
  other fail-closed harnesses.
- BUGBOT.md: record the new scheduled-only, never-PR-gating workflow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .cursor/BUGBOT.md                       |   4 +
 .github/workflows/build.yml             |  11 ++
 .github/workflows/pin-version-drift.yml |  61 +++++++++
 scripts/check-pin-version.sh            | 163 ++++++++++++++++++++++++
 scripts/tests/pin-version-verify.sh     | 114 +++++++++++++++++
 5 files changed, 353 insertions(+)
 create mode 100644 .github/workflows/pin-version-drift.yml
 create mode 100755 scripts/check-pin-version.sh
 create mode 100755 scripts/tests/pin-version-verify.sh

diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
index 86525c2..de4a745 100644
--- a/.cursor/BUGBOT.md
+++ b/.cursor/BUGBOT.md
@@ -152,6 +152,10 @@ Two things make this repo unusual and should shape every finding:
 - `test/integration/*` uses 30s–5min timeouts because it drives a real cluster — not the
   production timeout convention.
 - `mutation.yml` and `head-drift-canary.yml` are advisory and never gate a merge.
+  `pin-version-drift.yml` is scheduled-only (no `pull_request` trigger) and fails CLOSED on
+  data-ingestors contract-version drift — a red scheduled run is the signal, by design; it still
+  never gates a PR merge, and gating PRs on live upstream is the backend#1009 failure it avoids
+  (backend#2704).
 - No `vendor/` directory — the module cache is used on purpose.
 - `// style-guard: allow` is a defined escape hatch but is currently used nowhere; if one
   appears, it is a novel exception worth scrutiny rather than an accepted pattern.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 405a368..7265b0e 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -87,6 +87,10 @@ jobs:
           bash -n scripts/tests/install-verify.sh
           shellcheck --shell=bash --severity=error scripts/tests/install-ps1-verify.sh
           bash -n scripts/tests/install-ps1-verify.sh
+          shellcheck --shell=bash --severity=error scripts/check-pin-version.sh
+          shellcheck --shell=bash --severity=error scripts/tests/pin-version-verify.sh
+          bash -n scripts/check-pin-version.sh
+          bash -n scripts/tests/pin-version-verify.sh
       # format.sh's own fail-closed properties. Formatters are stubbed, so this is
       # hermetic and needs no Go toolchain — which is why it lives in this job
       # rather than Lint. It exists because the first cut of format.sh reported
@@ -108,6 +112,13 @@ jobs:
       # since "cannot tell" is not evidence that verification is mandatory.
       - name: Verification harness — Windows (mandatory cosign / fail-closed)
         run: bash scripts/tests/install-ps1-verify.sh
+      # check-pin-version.sh's fail-closed properties: contract-version DRIFT
+      # reddens (exit 1) and every "cannot evaluate" reddens (exit 2). Fetches
+      # are file:// URLs and the pin/branch are injected, so this is hermetic
+      # and needs no network — the live pin-vs-HEAD comparison is the scheduled
+      # pin-version-drift.yml, which must never gate a PR (backend#2704 / #1009).
+      - name: Pin-version watcher harness (drift reddens / fail-closed)
+        run: bash scripts/tests/pin-version-verify.sh
 
   test:
     timeout-minutes: 15
diff --git a/.github/workflows/pin-version-drift.yml b/.github/workflows/pin-version-drift.yml
new file mode 100644
index 0000000..8b6980e
--- /dev/null
+++ b/.github/workflows/pin-version-drift.yml
@@ -0,0 +1,61 @@
+name: Contract-version drift (pin freshness)
+
+# Watches the data-ingestors pin ITSELF for contract-version staleness
+# (backend#2704). scripts/sync-schema.sh --check (build.yml) answers "does my
+# vendored copy match the SHA I pinned?"; it never answers "is the SHA I pinned
+# still current?" So the pin sat a whole contract VERSION behind (layout v2 vs
+# data-ingestors@develop v3) while every drift gate stayed green.
+#
+# This job resolves scripts/.data-ingestors-ref, resolves data-ingestors'
+# current default branch, and compares the CONTRACT VERSION — the top-level
+# "version" in tracebloc_ingestor/schema/layout.v1.json — at the pin vs at HEAD.
+# Version, NOT commit distance: 180 unrelated upstream commits are fine, a
+# version bump is the finding (scripts/check-pin-version.sh).
+#
+# SCHEDULED, never a PR gate. Gating open PRs on live upstream is precisely the
+# backend#1009 failure this repo removed by pinning — an unrelated upstream
+# bump would red every open PR. So there is no `pull_request` trigger here; the
+# checker's own logic is guarded on PRs by its hermetic unit test
+# (scripts/tests/pin-version-verify.sh, run in build.yml), which touches no
+# network. The pinned PR comparison (sync-schema.sh --check) is left unchanged.
+#
+# FAIL CLOSED. A red run is the signal: version drift (exit 1) AND any
+# "cannot evaluate" — absent/malformed pin, moved path, unreachable raw URL,
+# non-JSON, missing "version" (exit 2) — both fail the job. "Cannot tell" is a
+# finding, never a green pass.
+#
+# Complements head-drift-canary.yml (weekly, advisory, never-blocking, opens a
+# tracking issue on ANY mirrored-source change). This one is narrower and
+# harder: a fail-closed gate on the semantic contract VERSION specifically.
+#
+# data-ingestors is public, so github.token suffices for the `gh api`
+# default-branch lookup and the raw fetches. If it ever goes private, add a
+# read token (CROSS_REPO_READ_TOKEN) the way head-drift-canary.yml does.
+
+on:
+  schedule:
+    - cron: "30 6 * * 1" # weekly Monday 06:30 UTC — after head-drift-canary (06:00)
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pin-version-drift
+  cancel-in-progress: false
+
+jobs:
+  contract-version:
+    timeout-minutes: 10
+    name: Pinned contract version vs HEAD (fail-closed)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Compare pinned contract version against data-ingestors HEAD
+        # GH_TOKEN lets `gh api` resolve the current default branch. python3 and
+        # curl are preinstalled on ubuntu-latest. Non-zero exit (drift OR
+        # cannot-evaluate) reds this run by design — that IS the finding.
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./scripts/check-pin-version.sh
diff --git a/scripts/check-pin-version.sh b/scripts/check-pin-version.sh
new file mode 100755
index 0000000..6398a39
--- /dev/null
+++ b/scripts/check-pin-version.sh
@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# =============================================================================
+#  check-pin-version.sh — is the pinned data-ingestors contract still the
+#  CURRENT contract version?  (backend#2704)
+#
+#  scripts/sync-schema.sh --check answers one question well: "does my vendored
+#  copy match the SHA I pinned?" It never answers the second: "is the SHA I
+#  pinned still current?" So the pin can sit six weeks / a whole contract
+#  VERSION behind while every drift gate stays green — which is exactly what
+#  happened (pin on layout contract v2, data-ingestors@develop on v3).
+#
+#  The pin is deliberate and must stay (backend#1009: a floating ref reds every
+#  open CLI PR on unrelated upstream commits). This script does NOT float it. It
+#  is the watcher for the pin ITSELF: resolve the pin, resolve data-ingestors'
+#  current default branch, fetch the dataset-layout contract at BOTH refs, and
+#  compare the CONTRACT VERSION — the top-level "version" string in
+#  tracebloc_ingestor/schema/layout.v1.json.
+#
+#  VERSION, not commit distance. 180 unrelated upstream commits that never touch
+#  the version are fine and stay green; a single version bump is the finding.
+#  This is why it is a SCHEDULED job, never a PR gate: gating PRs on live
+#  upstream is the backend#1009 failure this repo already removed.
+#
+#  FAIL CLOSED. "Cannot tell" is a finding, never a pass — the guard already has
+#  one shape of "cannot tell reads as fine" (the pinned check going stale) and
+#  must not gain a second. An absent/malformed pin, a moved path, an unreachable
+#  raw URL, a non-JSON body, or a missing "version" all exit non-zero.
+#
+#  Exit codes:
+#    0  IN SYNC   — the pin is on the current contract version.
+#    1  DRIFT     — the pin's contract version differs from HEAD's. Re-pin
+#                   (scripts/.data-ingestors-ref) and re-run scripts/sync-schema.sh.
+#    2  FAIL CLOSED — could not evaluate (bad/absent pin, moved path, unreachable
+#                   URL, non-JSON, missing version). Never reported as agreement.
+#
+#  Env knobs (defaults are the production values; overrides exist for the
+#  hermetic test harness, scripts/tests/pin-version-verify.sh):
+#    REF_FILE                       pin file (default: scripts/.data-ingestors-ref)
+#    DATA_INGESTORS_REF             override the pin ref (default: from REF_FILE)
+#    DATA_INGESTORS_DEFAULT_BRANCH  override the upstream default branch
+#                                   (default: resolved via `gh api`)
+#    PIN_LAYOUT_URL / HEAD_LAYOUT_URL  full URL overrides for the two fetches
+#                                   (default: built from the refs above)
+# =============================================================================
+set -uo pipefail
+
+# Where the vendored layout contract lives upstream — keep in lockstep with the
+# UPSTREAM_BASE/layout.v1.json path in scripts/sync-schema.sh.
+readonly UPSTREAM_BASE="https://raw.githubusercontent.com/tracebloc/data-ingestors"
+readonly LAYOUT_SUBPATH="tracebloc_ingestor/schema/layout.v1.json"
+
+REF_FILE="${REF_FILE:-$(cd "$(dirname "$0")" && pwd)/.data-ingestors-ref}"
+
+die_closed() { echo "FAIL CLOSED: $*" >&2; exit 2; }
+
+# A ref is interpolated into a raw.githubusercontent URL, so validate its shape
+# before use — same guard as sync-schema.sh / chart-drift.yml: alnum start, then
+# alnum . _ - / and no ".." component. Blocks path-traversal / extra segments.
+valid_ref_shape() {
+  grep -qE '^[A-Za-z0-9][A-Za-z0-9._/-]*$' <<<"$1" && ! grep -q '\.\.' <<<"$1"
+}
+
+# Resolve the pin: first non-comment, non-blank line of REF_FILE (the rule
+# sync-schema.sh uses), overridable via DATA_INGESTORS_REF.
+resolve_pin() {
+  if [[ -n "${DATA_INGESTORS_REF:-}" ]]; then
+    printf '%s' "$DATA_INGESTORS_REF"; return 0
+  fi
+  [[ -f "$REF_FILE" ]] || return 1
+  grep -vE '^[[:space:]]*(#|$)' "$REF_FILE" 2>/dev/null | head -1 | tr -d '[:space:]'
+}
+
+# Resolve data-ingestors' CURRENT default branch, overridable for tests. Uses
+# `gh api` (needs GH_TOKEN in CI); a public repo's metadata reads with the
+# default workflow token.
+resolve_default_branch() {
+  if [[ -n "${DATA_INGESTORS_DEFAULT_BRANCH:-}" ]]; then
+    printf '%s' "$DATA_INGESTORS_DEFAULT_BRANCH"; return 0
+  fi
+  local b
+  b="$(gh api repos/tracebloc/data-ingestors --jq .default_branch 2>/dev/null)"
+  # gh emits nothing on failure and the literal "null" when the field is absent
+  # (a 200 with an unexpected body). Treat both as unresolved so main's -n check
+  # fail-closes on the real cause instead of curling a `.../null/...` URL.
+  [[ -n "$b" && "$b" != "null" ]] || return 1
+  printf '%s' "$b"
+}
+
+# fetch_version <url> <label> — echo the top-level "version" string on success;
+# any failure (fetch, non-JSON, missing/empty/non-scalar version) returns
+# non-zero so the caller fail-closes. The body is captured into a variable, not
+# a temp file: fetch_version is called as `$(fetch_version ...)`, i.e. in a
+# subshell where an EXIT trap is reset and a `_tmpfiles+=` would be invisible to
+# the parent — so a temp file here would leak. No temp file, nothing to clean.
+fetch_version() {
+  local url="$1" label="$2" body ver
+  # -f: HTTP errors (404 moved-path) are failures; time bounds keep a hung
+  # endpoint from wedging the run. Mirrors sync-schema.sh's curl.
+  if ! body="$(curl -fsSL --tlsv1.2 --connect-timeout 10 --max-time 60 "$url")"; then
+    echo "  could not fetch the $label contract: $url" >&2
+    return 1
+  fi
+  # python3 exits non-zero on a non-JSON body or a missing/empty/non-scalar
+  # "version"; pipefail carries that exit to the `if !`.
+  # shellcheck disable=SC2016  # the $-expressions are Python, not shell
+  if ! ver="$(printf '%s' "$body" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+v = data.get("version")
+if not isinstance(v, (str, int)) or isinstance(v, bool) or str(v).strip() == "":
+    sys.exit(1)
+print(str(v).strip())
+')"; then
+    echo "  the $label contract is not JSON, or has no top-level \"version\": $url" >&2
+    return 1
+  fi
+  printf '%s' "$ver"
+}
+
+main() {
+  local pin default_branch pin_url head_url pin_ver head_ver
+
+  pin="$(resolve_pin)"
+  [[ -n "$pin" ]] || die_closed "no ref in ${REF_FILE} (first non-comment line must be a commit SHA)"
+  valid_ref_shape "$pin" || die_closed "invalid pin ref shape: '$pin'"
+
+  # Build the pin URL (overridable). The pin comes from the ref file above.
+  pin_url="${PIN_LAYOUT_URL:-${UPSTREAM_BASE}/${pin}/${LAYOUT_SUBPATH}}"
+
+  # Build the HEAD URL (overridable). Only resolve the default branch when the
+  # URL isn't overridden, so the test harness needs no `gh` and no network.
+  if [[ -n "${HEAD_LAYOUT_URL:-}" ]]; then
+    head_url="$HEAD_LAYOUT_URL"
+    default_branch="(HEAD_LAYOUT_URL override)"
+  else
+    default_branch="$(resolve_default_branch)"
+    [[ -n "$default_branch" ]] || die_closed "could not resolve data-ingestors' default branch (gh api)"
+    valid_ref_shape "$default_branch" || die_closed "invalid default-branch shape: '$default_branch'"
+    head_url="${UPSTREAM_BASE}/${default_branch}/${LAYOUT_SUBPATH}"
+  fi
+
+  pin_ver="$(fetch_version "$pin_url" "pinned")"  || die_closed "could not read the pinned contract version"
+  head_ver="$(fetch_version "$head_url" "HEAD")" || die_closed "could not read the HEAD contract version"
+
+  echo "data-ingestors dataset-layout contract version"
+  echo "  pin            ${pin}  ->  v${pin_ver}"
+  echo "  default branch ${default_branch}  ->  v${head_ver}"
+
+  if [[ "$pin_ver" == "$head_ver" ]]; then
+    echo "IN SYNC: the pin is on the current contract version (v${pin_ver})."
+    return 0
+  fi
+
+  echo "DRIFT: the pinned contract is v${pin_ver}, but data-ingestors HEAD is v${head_ver}." >&2
+  echo "The CLI's vendored layout/sidecar/help are derived from a stale contract version." >&2
+  echo "Fix: bump scripts/.data-ingestors-ref, run scripts/sync-schema.sh, commit the regenerated files (cli#286 shape)." >&2
+  return 1
+}
+
+main "$@"
diff --git a/scripts/tests/pin-version-verify.sh b/scripts/tests/pin-version-verify.sh
new file mode 100755
index 0000000..24b735c
--- /dev/null
+++ b/scripts/tests/pin-version-verify.sh
@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# =============================================================================
+#  pin-version-verify.sh — the properties scripts/check-pin-version.sh must not
+#  lose (backend#2704).
+#
+#  check-pin-version.sh is a fail-closed watcher: it must redden on a contract
+#  VERSION bump and on every "cannot evaluate" shape, and stay green ONLY when
+#  the pinned version equals HEAD's. An inert checker and a working one look
+#  identical in a green scheduled log, so this harness mutation-proves the two
+#  that matter — DRIFT reddens (exit 1), and each cannot-evaluate reddens
+#  (exit 2) — the way backend#2704 asks for.
+#
+#  HERMETIC AND FAST: every fetch is a `file://` URL into a temp dir, the pin
+#  and default branch are injected via env, so nothing here touches the network
+#  or needs `gh`. That means these cases assert check-pin-version.sh's own
+#  logic — version compare, fail-closed, shape guard — not data-ingestors'
+#  behaviour. The live end-to-end check is the scheduled workflow itself.
+#
+#  Usage: bash scripts/tests/pin-version-verify.sh
+# =============================================================================
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CHECKER="${REPO_ROOT}/scripts/check-pin-version.sh"
+[ -f "$CHECKER" ] || { echo "pin-version-verify: no scripts/check-pin-version.sh — refusing to report pass" >&2; exit 2; }
+
+pass=0
+fail=0
+ok()  { echo "  ok:   $1"; pass=$((pass + 1)); }
+bad() { echo "  FAIL: $1" >&2; fail=$((fail + 1)); }
+
+FIX="$(mktemp -d "${TMPDIR:-/tmp}/pinver.XXXXXX")" || exit 2
+trap 'rm -rf "$FIX"' EXIT INT TERM
+
+printf '{"tasks":{},"version":"2"}\n'  > "$FIX/v2.json"
+printf '{"tasks":{},"version":"3"}\n'  > "$FIX/v3.json"
+printf '{"tasks":{}}\n'                > "$FIX/noversion.json"
+printf '<html>not json</html>\n'       > "$FIX/notjson.txt"
+
+# run_case <name> <expected-exit> <extra env assignments...>
+# Runs the checker with URL/ref overrides and asserts the exit code. A dummy
+# DATA_INGESTORS_REF of valid shape stands in for the pin. EVERY case below also
+# sets HEAD_LAYOUT_URL, so the checker never takes the default-branch path — the
+# bogus DATA_INGESTORS_DEFAULT_BRANCH only backstops the `gh api` lookup. It is
+# NOT a full offline guarantee: dropping a case's HEAD_LAYOUT_URL would curl
+# raw.githubusercontent.com with this value, so keep every case's HEAD_LAYOUT_URL
+# set. That, not this env var, is what keeps the harness hermetic.
+run_case() {
+  local name="$1" want="$2"; shift 2
+  local out rc
+  out="$(env "$@" \
+    DATA_INGESTORS_DEFAULT_BRANCH="unused-in-tests" \
+    "$CHECKER" 2>&1)"
+  rc=$?
+  if [ "$rc" -eq "$want" ]; then
+    ok "$name (exit $rc)"
+  else
+    bad "$name — expected exit $want, got $rc"
+    echo "$out" | sed 's/^/        /' >&2
+  fi
+}
+
+echo "check-pin-version.sh — fail-closed contract-version watcher"
+
+# 0 — IN SYNC: pin version == HEAD version.
+run_case "in-sync: v2 == v2 -> pass" 0 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json" \
+  HEAD_LAYOUT_URL="file://$FIX/v2.json"
+
+# 1 — DRIFT: the mutation-proof. pin v2, HEAD v3 MUST redden (exit 1). If the
+#     version comparison is ever made inert, this is the case that fails.
+run_case "drift: pin v2 vs HEAD v3 -> exit 1" 1 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json" \
+  HEAD_LAYOUT_URL="file://$FIX/v3.json"
+
+# 2 — FAIL CLOSED: HEAD URL unreachable (moved path / dead raw URL).
+run_case "fail-closed: unreachable HEAD url -> exit 2" 2 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json" \
+  HEAD_LAYOUT_URL="file://$FIX/does-not-exist.json"
+
+# 3 — FAIL CLOSED: contract JSON is missing the top-level "version".
+run_case "fail-closed: missing version field -> exit 2" 2 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  PIN_LAYOUT_URL="file://$FIX/noversion.json" \
+  HEAD_LAYOUT_URL="file://$FIX/v3.json"
+
+# 4 — FAIL CLOSED: response is not JSON.
+run_case "fail-closed: non-JSON body -> exit 2" 2 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  PIN_LAYOUT_URL="file://$FIX/notjson.txt" \
+  HEAD_LAYOUT_URL="file://$FIX/v3.json"
+
+# 5 — FAIL CLOSED: pin file has no ref (comment-only). Must exit 2 before any
+#     fetch — URL overrides are set only so nothing touches the network if the
+#     resolution order ever regresses.
+printf '# just a comment, no ref\n' > "$FIX/empty-ref"
+run_case "fail-closed: empty pin (comment-only ref file) -> exit 2" 2 \
+  REF_FILE="$FIX/empty-ref" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json" \
+  HEAD_LAYOUT_URL="file://$FIX/v3.json"
+
+# 6 — FAIL CLOSED: pin ref has a traversal-shaped value ("..").
+printf 'main/../../etc\n' > "$FIX/bad-shape-ref"
+run_case "fail-closed: malformed pin shape ('..') -> exit 2" 2 \
+  REF_FILE="$FIX/bad-shape-ref" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json" \
+  HEAD_LAYOUT_URL="file://$FIX/v3.json"
+
+echo
+echo "pin-version-verify: $pass passed, $fail failed"
+[ "$fail" -eq 0 ] || exit 1

From 51fdb2f52fd483a3849b8f998e2c1e6b4cd8577b Mon Sep 17 00:00:00 2001
From: Arturo Peroni <arturo@tracebloc.io>
Date: Thu, 27 Aug 2026 17:24:59 +0200
Subject: [PATCH 2/2] fix(sync): file a tracking issue on pin-version drift +
 derive the layout path (backend#2704)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses LukasWodka's review on cli#595.

- A red scheduled run was the ONLY signal — no issue, no assignee — so the first
  Monday cron would red, nobody would be told, and red would become the
  workflow's normal state. pin-version-drift.yml now opens/updates ONE
  `pin-version-drift`-labelled tracking issue (create-or-update, like
  head-drift-canary.yml) on drift OR any cannot-evaluate, AND still fails closed.
  Red run + filed issue: the finding lands where a person sees it, and "cannot
  tell" is still never a green pass. Chose this over sequencing the re-pin so the
  watcher's value doesn't hinge on landing a second PR before Monday 06:30 UTC.
- The vendored layout path is now DERIVED from sync-schema.sh
  (derive_layout_subpath) instead of held behind a "keep in lockstep" comment —
  the claim is now a machine check, asserted by pin-version-verify.sh, and fails
  closed if sync-schema.sh's declarations move. main derives it only when a URL
  isn't overridden, so the hermetic harness stays offline. check-pin-version.sh
  is source-guarded so the test can call the function directly.

Verify: 9/9 hermetic cases (added unparseable-sync-schema fail-closed + the
derivation assertion); shellcheck --severity=error + bash -n clean; both
workflows YAML-valid; live: real pin v2 vs develop v3 -> exit 1, develop vs
develop -> exit 0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .cursor/BUGBOT.md                       |  9 +--
 .github/workflows/pin-version-drift.yml | 87 +++++++++++++++++++++----
 scripts/check-pin-version.sh            | 53 ++++++++++++---
 scripts/tests/pin-version-verify.sh     | 22 +++++++
 4 files changed, 147 insertions(+), 24 deletions(-)

diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
index de4a745..261320b 100644
--- a/.cursor/BUGBOT.md
+++ b/.cursor/BUGBOT.md
@@ -152,10 +152,11 @@ Two things make this repo unusual and should shape every finding:
 - `test/integration/*` uses 30s–5min timeouts because it drives a real cluster — not the
   production timeout convention.
 - `mutation.yml` and `head-drift-canary.yml` are advisory and never gate a merge.
-  `pin-version-drift.yml` is scheduled-only (no `pull_request` trigger) and fails CLOSED on
-  data-ingestors contract-version drift — a red scheduled run is the signal, by design; it still
-  never gates a PR merge, and gating PRs on live upstream is the backend#1009 failure it avoids
-  (backend#2704).
+  `pin-version-drift.yml` is scheduled-only (no `pull_request` trigger): on data-ingestors
+  contract-version drift (or any cannot-evaluate) it opens/updates a `pin-version-drift`-labelled
+  tracking issue AND fails closed — a red scheduled run plus a filed issue is the intended signal.
+  It still never gates a PR merge; gating PRs on live upstream is the backend#1009 failure it
+  avoids (backend#2704).
 - No `vendor/` directory — the module cache is used on purpose.
 - `// style-guard: allow` is a defined escape hatch but is currently used nowhere; if one
   appears, it is a novel exception worth scrutiny rather than an accepted pattern.
diff --git a/.github/workflows/pin-version-drift.yml b/.github/workflows/pin-version-drift.yml
index 8b6980e..775a1a5 100644
--- a/.github/workflows/pin-version-drift.yml
+++ b/.github/workflows/pin-version-drift.yml
@@ -19,14 +19,14 @@ name: Contract-version drift (pin freshness)
 # (scripts/tests/pin-version-verify.sh, run in build.yml), which touches no
 # network. The pinned PR comparison (sync-schema.sh --check) is left unchanged.
 #
-# FAIL CLOSED. A red run is the signal: version drift (exit 1) AND any
+# FAIL CLOSED, AND it reaches a person. On version drift (checker exit 1) or any
 # "cannot evaluate" — absent/malformed pin, moved path, unreachable raw URL,
-# non-JSON, missing "version" (exit 2) — both fail the job. "Cannot tell" is a
-# finding, never a green pass.
-#
-# Complements head-drift-canary.yml (weekly, advisory, never-blocking, opens a
-# tracking issue on ANY mirrored-source change). This one is narrower and
-# harder: a fail-closed gate on the semantic contract VERSION specifically.
+# non-JSON, missing "version", unparseable sync-schema.sh (exit 2) — the job
+# opens or updates ONE tracking issue (label `pin-version-drift`) AND then fails.
+# The issue is why a red run isn't the *only* signal: a scheduled red that no one
+# is assigned to would quietly become this workflow's normal state (LukasWodka on
+# cli#595). The finding lands where a person sees it, the way head-drift-canary.yml
+# does; the job also reds, so "cannot tell" is never a green pass.
 #
 # data-ingestors is public, so github.token suffices for the `gh api`
 # default-branch lookup and the raw fetches. If it ever goes private, add a
@@ -39,6 +39,7 @@ on:
 
 permissions:
   contents: read
+  issues: write
 
 concurrency:
   group: pin-version-drift
@@ -53,9 +54,73 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Compare pinned contract version against data-ingestors HEAD
-        # GH_TOKEN lets `gh api` resolve the current default branch. python3 and
-        # curl are preinstalled on ubuntu-latest. Non-zero exit (drift OR
-        # cannot-evaluate) reds this run by design — that IS the finding.
+        id: check
+        # Capture the checker's exit WITHOUT failing the step, so the reporting
+        # step can run before the job reds. GH_TOKEN lets `gh api` resolve the
+        # current default branch. python3 and curl are preinstalled on ubuntu.
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          rc=0
+          ./scripts/check-pin-version.sh > check-out.txt 2>&1 || rc=$?
+          cat check-out.txt
+          echo "rc=$rc" >> "$GITHUB_OUTPUT"
+          case "$rc" in
+            0) echo "state=in_sync" >> "$GITHUB_OUTPUT" ;;
+            1) echo "state=drift"   >> "$GITHUB_OUTPUT" ;;
+            *) echo "state=blocked" >> "$GITHUB_OUTPUT" ;;
+          esac
+
+      - name: Open or update the pin-version-drift tracking issue
+        if: steps.check.outputs.rc != '0'
         env:
           GH_TOKEN: ${{ github.token }}
-        run: ./scripts/check-pin-version.sh
+          REPO: ${{ github.repository }}
+          STATE: ${{ steps.check.outputs.state }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ "$STATE" = "drift" ]; then
+            title="data-ingestors contract version has moved past the CLI's pin"
+            headline="The pinned data-ingestors layout contract is a VERSION behind HEAD."
+          else
+            title="pin-version-drift watcher could not evaluate the pin (fail-closed)"
+            headline="The watcher could not evaluate the pin and fail-closed — this is a finding, not agreement."
+          fi
+          # shellcheck disable=SC2016  # printf formats carry markdown backticks, not shell expansions
+          {
+            printf '<!-- pin-version-drift -->\n'
+            printf '**%s**\n\n' "$headline"
+            printf '**Scheduled run:** %s\n\n' "$RUN_URL"
+            printf '```\n'
+            cat check-out.txt
+            printf '\n```\n\n'
+            if [ "$STATE" = "drift" ]; then
+              printf '**Fix (cli#286 shape):** bump `scripts/.data-ingestors-ref`, run `scripts/sync-schema.sh`, and commit the regenerated `internal/schema/*` in one deliberate PR. Close this issue when that lands.\n'
+            else
+              printf 'A bad/absent pin, a moved path, an unreachable raw URL, a non-JSON body, a missing `"version"`, or an unparseable `sync-schema.sh` all land here — "cannot tell" is never a green pass. Fix the cause (see the run log), then re-run this workflow. Close this issue once a run is clean.\n'
+            fi
+          } > body.md
+          gh label create pin-version-drift --repo "$REPO" --force \
+            --description "auto-filed by pin-version-drift.yml (backend#2704)" --color D93F0B
+          # Keyed by the label so there is at most ONE open issue; refresh its
+          # title each run so it reflects the current failure mode.
+          existing="$(gh issue list --repo "$REPO" --label pin-version-drift --state open \
+            --json number --jq '.[0].number // empty')"
+          if [ -n "$existing" ]; then
+            echo "updating existing tracking issue #$existing"
+            gh issue edit "$existing" --repo "$REPO" --title "$title"
+            gh issue comment "$existing" --repo "$REPO" --body-file body.md
+          else
+            echo "opening new tracking issue"
+            gh issue create --repo "$REPO" --title "$title" --body-file body.md --label pin-version-drift
+          fi
+
+      - name: Fail closed on drift or cannot-evaluate
+        if: steps.check.outputs.rc != '0'
+        run: |
+          echo "::error::pin-version watcher exit ${{ steps.check.outputs.rc }} (${{ steps.check.outputs.state }}) — a tracking issue was opened/updated (label: pin-version-drift)."
+          exit 1
+
+      - name: All clear
+        if: steps.check.outputs.rc == '0'
+        run: echo "::notice::Pinned contract version matches data-ingestors HEAD."
diff --git a/scripts/check-pin-version.sh b/scripts/check-pin-version.sh
index 6398a39..621d0bd 100755
--- a/scripts/check-pin-version.sh
+++ b/scripts/check-pin-version.sh
@@ -31,11 +31,14 @@
 #    1  DRIFT     — the pin's contract version differs from HEAD's. Re-pin
 #                   (scripts/.data-ingestors-ref) and re-run scripts/sync-schema.sh.
 #    2  FAIL CLOSED — could not evaluate (bad/absent pin, moved path, unreachable
-#                   URL, non-JSON, missing version). Never reported as agreement.
+#                   URL, non-JSON, missing version, or an unparseable
+#                   sync-schema.sh). Never reported as agreement.
 #
 #  Env knobs (defaults are the production values; overrides exist for the
 #  hermetic test harness, scripts/tests/pin-version-verify.sh):
 #    REF_FILE                       pin file (default: scripts/.data-ingestors-ref)
+#    SYNC_SCHEMA_SH                 source of the vendored layout path
+#                                   (default: scripts/sync-schema.sh)
 #    DATA_INGESTORS_REF             override the pin ref (default: from REF_FILE)
 #    DATA_INGESTORS_DEFAULT_BRANCH  override the upstream default branch
 #                                   (default: resolved via `gh api`)
@@ -44,12 +47,14 @@
 # =============================================================================
 set -uo pipefail
 
-# Where the vendored layout contract lives upstream — keep in lockstep with the
-# UPSTREAM_BASE/layout.v1.json path in scripts/sync-schema.sh.
 readonly UPSTREAM_BASE="https://raw.githubusercontent.com/tracebloc/data-ingestors"
-readonly LAYOUT_SUBPATH="tracebloc_ingestor/schema/layout.v1.json"
 
-REF_FILE="${REF_FILE:-$(cd "$(dirname "$0")" && pwd)/.data-ingestors-ref}"
+_here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REF_FILE="${REF_FILE:-${_here}/.data-ingestors-ref}"
+# sync-schema.sh is the single source of truth for the vendored layout path;
+# see derive_layout_subpath. SYNC_SCHEMA_SH lets the test harness point at a
+# fixture.
+SYNC_SCHEMA_SH="${SYNC_SCHEMA_SH:-${_here}/sync-schema.sh}"
 
 die_closed() { echo "FAIL CLOSED: $*" >&2; exit 2; }
 
@@ -60,6 +65,24 @@ valid_ref_shape() {
   grep -qE '^[A-Za-z0-9][A-Za-z0-9._/-]*$' <<<"$1" && ! grep -q '\.\.' <<<"$1"
 }
 
+# Derive the upstream layout path (tracebloc_ingestor/schema/layout.v1.json)
+# from sync-schema.sh instead of holding a second copy: sync-schema.sh is the
+# single source of truth for the vendored path, so a moved schema dir there
+# changes both in one place, and the old "keep in lockstep" comment becomes an
+# actual check (LukasWodka on cli#595; pin-version-verify.sh asserts the derived
+# value). Returns non-zero — the caller fail-closes — if either declaration it
+# parses is gone. It parses these two sync-schema.sh lines:
+#   UPSTREAM_BASE="...:${DATA_INGESTORS_REF}/<dir>"
+#   "${UPSTREAM_BASE}/<file>|internal/schema/layout.v1.json"
+derive_layout_subpath() {
+  [[ -f "$SYNC_SCHEMA_SH" ]] || { echo "  no sync-schema.sh at $SYNC_SCHEMA_SH" >&2; return 1; }
+  local dir file
+  dir="$(grep -oE 'DATA_INGESTORS_REF\}/[A-Za-z0-9._/-]+' "$SYNC_SCHEMA_SH" | head -1 | sed -E 's#^DATA_INGESTORS_REF\}/##')"
+  file="$(grep -oE 'UPSTREAM_BASE\}/[A-Za-z0-9._-]+\.json\|internal/schema/layout\.v1\.json' "$SYNC_SCHEMA_SH" | head -1 | sed -E 's#^UPSTREAM_BASE\}/##; s#\|.*$##')"
+  [[ -n "$dir" && -n "$file" ]] || { echo "  could not parse the layout path from $SYNC_SCHEMA_SH" >&2; return 1; }
+  printf '%s/%s' "$dir" "$file"
+}
+
 # Resolve the pin: first non-comment, non-blank line of REF_FILE (the rule
 # sync-schema.sh uses), overridable via DATA_INGESTORS_REF.
 resolve_pin() {
@@ -121,14 +144,22 @@ print(str(v).strip())
 }
 
 main() {
-  local pin default_branch pin_url head_url pin_ver head_ver
+  local pin default_branch pin_url head_url pin_ver head_ver layout_subpath=""
 
   pin="$(resolve_pin)"
   [[ -n "$pin" ]] || die_closed "no ref in ${REF_FILE} (first non-comment line must be a commit SHA)"
   valid_ref_shape "$pin" || die_closed "invalid pin ref shape: '$pin'"
 
+  # Derive the layout path only when we actually build a URL from it — the test
+  # harness overrides both URLs and then needs neither sync-schema.sh nor a
+  # network fetch.
+  if [[ -z "${PIN_LAYOUT_URL:-}" || -z "${HEAD_LAYOUT_URL:-}" ]]; then
+    layout_subpath="$(derive_layout_subpath)" \
+      || die_closed "could not derive the layout path from ${SYNC_SCHEMA_SH} (its format changed?)"
+  fi
+
   # Build the pin URL (overridable). The pin comes from the ref file above.
-  pin_url="${PIN_LAYOUT_URL:-${UPSTREAM_BASE}/${pin}/${LAYOUT_SUBPATH}}"
+  pin_url="${PIN_LAYOUT_URL:-${UPSTREAM_BASE}/${pin}/${layout_subpath}}"
 
   # Build the HEAD URL (overridable). Only resolve the default branch when the
   # URL isn't overridden, so the test harness needs no `gh` and no network.
@@ -139,7 +170,7 @@ main() {
     default_branch="$(resolve_default_branch)"
     [[ -n "$default_branch" ]] || die_closed "could not resolve data-ingestors' default branch (gh api)"
     valid_ref_shape "$default_branch" || die_closed "invalid default-branch shape: '$default_branch'"
-    head_url="${UPSTREAM_BASE}/${default_branch}/${LAYOUT_SUBPATH}"
+    head_url="${UPSTREAM_BASE}/${default_branch}/${layout_subpath}"
   fi
 
   pin_ver="$(fetch_version "$pin_url" "pinned")"  || die_closed "could not read the pinned contract version"
@@ -160,4 +191,8 @@ main() {
   return 1
 }
 
-main "$@"
+# Run main only when executed directly, not when sourced — so the test harness
+# can source this file and call derive_layout_subpath in isolation.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi
diff --git a/scripts/tests/pin-version-verify.sh b/scripts/tests/pin-version-verify.sh
index 24b735c..0700b67 100755
--- a/scripts/tests/pin-version-verify.sh
+++ b/scripts/tests/pin-version-verify.sh
@@ -109,6 +109,28 @@ run_case "fail-closed: malformed pin shape ('..') -> exit 2" 2 \
   PIN_LAYOUT_URL="file://$FIX/v2.json" \
   HEAD_LAYOUT_URL="file://$FIX/v3.json"
 
+# 7 — FAIL CLOSED: the layout path can't be derived (sync-schema.sh missing).
+#     One URL is left un-overridden so main actually reaches the derivation; it
+#     must die_closed BEFORE any network fetch, so no real URL is contacted.
+run_case "fail-closed: unparseable sync-schema.sh -> exit 2" 2 \
+  DATA_INGESTORS_REF="0123456789abcdef0123456789abcdef01234567" \
+  SYNC_SCHEMA_SH="$FIX/no-such-sync-schema.sh" \
+  PIN_LAYOUT_URL="file://$FIX/v2.json"
+
+# 8 — the "keep in lockstep" comment turned into a check: the path DERIVED from
+#     the real scripts/sync-schema.sh must equal the known layout subpath. Source
+#     the checker (main is source-guarded) and call the function directly. If
+#     sync-schema.sh's declarations move and the parser stops matching, this
+#     reddens instead of the mismatch going unnoticed.
+WANT_SUBPATH="tracebloc_ingestor/schema/layout.v1.json"
+got_subpath="$(SYNC_SCHEMA_SH="$REPO_ROOT/scripts/sync-schema.sh" \
+  bash -c 'source "$1"; derive_layout_subpath' pin-version-verify "$CHECKER" 2>/dev/null)"
+if [ "$got_subpath" = "$WANT_SUBPATH" ]; then
+  ok "derive_layout_subpath matches sync-schema.sh ($got_subpath)"
+else
+  bad "derive_layout_subpath — want '$WANT_SUBPATH', got '$got_subpath'"
+fi
+
 echo
 echo "pin-version-verify: $pass passed, $fail failed"
 [ "$fail" -eq 0 ] || exit 1