@augurworks/augur 0.15.1

package/templates/shell/engine-bump.yml

@@ -0,0 +1,142 @@
+name: Bump engine pin
+
+# The public engine moves on its own cadence; this instance takes updates on ITS OWN
+# schedule. The pull lives ENTIRELY on this side: the engine repo knows nothing about
+# this shell (no dispatch wiring, no secrets upstream), and the pin doubles as this
+# instance's release valve — upstream can move fast, updates land only when you say so.
+# Roll back any update by reverting the pin commit.
+#
+# TRACK picks the update channel:
+#   release (default) — weekly (or on demand) this job finds the engine's latest
+#     GitHub RELEASE, and opens a PR moving the pin to that tag with the release
+#     notes in the body. Review the notes, merge, and deploy.yml ships it.
+#     Nothing lands without a human reading what changed.
+#   main — moves the pin straight to the engine's current main and pushes (no PR).
+#     For development instances that dogfood the bleeding edge.
+#
+# Push + trigger use the workflow's own GITHUB_TOKEN. In main mode the push
+# deliberately does NOT retrigger workflows, so deploy.yml is started explicitly.
+# In release mode the PR merge is performed by a human, which triggers deploy.yml
+# through the normal push event.
+#
+# NB GitHub disables cron schedules after ~60 days without repo activity — the manual
+# workflow_dispatch always works.
+#
+# ONE-TIME SETUP for release mode: allow Actions to open PRs on this repo —
+# Settings → Actions → General → Workflow permissions → check "Allow GitHub
+# Actions to create and approve pull requests" (or:
+#   gh api -X PUT repos/<owner>/<shell>/actions/permissions/workflow \
+#     -f default_workflow_permissions=write -F can_approve_pull_request_reviews=true).
+
+on:
+  # The engine's own deploy-trigger.yml dispatches `engine-updated` the moment its main
+  # moves, to every shell named in its SHELL_REPO variable. Listening for it is what
+  # makes a shell update immediately instead of waiting for the next sweep — and
+  # without this trigger the dispatch arrives and does nothing, silently, which reads
+  # exactly like an instance that simply lags. The cron below stays as the fallback
+  # for whenever the dispatch does not arrive (token scope, fork, shell not in the list).
+  repository_dispatch:
+    types: [engine-updated]
+  schedule:
+    # Every 6 hours, not weekly. For an instance on the engine's SHELL_REPO list this
+    # is only a safety net — but a SELF-HOSTED instance is never on that list, so this
+    # cron is its ONLY automatic update, and a weekly sweep meant a security patch
+    # could sit unapplied for six days. Auto-update is the default because it is how
+    # fixes reach instances nobody is watching; detaching is a deliberate act (disable
+    # this workflow, or pin TRACK to a tag), never an accident of scheduling.
+    - cron: "17 */6 * * *" # 06:17 past every 6th hour UTC
+  workflow_dispatch:
+
+env:
+  # SET BEFORE USE — this is an instance choice, not a default to leave alone:
+  #   release  follow tagged releases. A human cuts the tag, so an update never
+  #            lands unread. Costs a lag, and it fails QUIETLY if tagging stops:
+  #            an instance once followed tags, none were cut for months, and its
+  #            pin drifted 87 commits behind the engine while looking healthy.
+  #   main     follow the engine's main. Always current, nothing to remember to
+  #            cut, no silent stall — at the price of taking changes unread.
+  # Pick deliberately, and if you pick `release`, make sure something actually
+  # cuts tags (see the engine's own release cadence).
+  TRACK: release
+
+permissions:
+  contents: write      # push the pin-bump commit / branch
+  pull-requests: write # open the release-update PR
+  actions: write       # start deploy.yml via workflow_dispatch (main mode)
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Move the engine pin
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          ENGINE_URL="$(git config -f .gitmodules submodule.engine.url)"
+          ENGINE_REPO="$(echo "$ENGINE_URL" | sed -E 's#(git@github.com:|https://github.com/)##; s#\.git$##')"
+          CUR_SHA="$(git ls-tree HEAD engine | awk '{print $3}')"
+          git config user.name "augur-bot"
+          git config user.email "augur-bot@users.noreply.github.com"
+
+          if [ "$TRACK" = "main" ]; then
+            NEW_SHA="$(git ls-remote "$ENGINE_URL" refs/heads/main | cut -f1)"
+            [ -n "$NEW_SHA" ] || { echo "::error::could not resolve the engine's main"; exit 1; }
+            [ "$NEW_SHA" != "$CUR_SHA" ] || { echo "Engine pin already at $NEW_SHA — nothing to do."; exit 0; }
+            git update-index --cacheinfo "160000,$NEW_SHA,engine"
+            git commit -m "Bump engine pin → ${NEW_SHA:0:12}"
+            # RETRY ON A LOST RACE, because losing one silently strands the instance.
+            # Anyone pushing to this shell while the bump runs — a doc edit, a config
+            # change — makes the push non-fast-forward. That failure is not "try again
+            # later": nothing tries again until the next engine push or the next cron
+            # sweep, so the instance sits on a stale engine and nothing says so. Observed
+            # on a live shell, one second apart.
+            #
+            # The retry RE-APPLIES the pin onto whatever landed, rather than rebasing:
+            # this checkout is shallow (actions/checkout fetches one commit), so a rebase
+            # has no common ancestor to work from and fails for a reason that has nothing
+            # to do with the conflict. Re-applying needs no history at all, and it is
+            # exactly as correct — the commit sets ONE value, a submodule pointer that was
+            # resolved before the loop.
+            pushed=""
+            for attempt in 1 2 3; do
+              if git push origin HEAD:main; then pushed=1; break; fi
+              echo "push rejected (attempt $attempt) — someone else pushed; re-applying the pin"
+              git fetch origin main
+              git reset --hard FETCH_HEAD
+              if [ "$(git ls-tree HEAD engine | awk '{print $3}')" = "$NEW_SHA" ]; then
+                echo "Another run already pinned ${NEW_SHA:0:12} — nothing to do."; exit 0
+              fi
+              git update-index --cacheinfo "160000,$NEW_SHA,engine"
+              git commit -m "Bump engine pin → ${NEW_SHA:0:12}"
+            done
+            [ -n "$pushed" ] || { echo "::error::could not push the pin bump after 3 attempts"; exit 1; }
+            echo "Bumped engine pin: ${CUR_SHA:0:12} → ${NEW_SHA:0:12} — starting deploy.yml"
+            gh workflow run deploy.yml --ref main
+            exit 0
+          fi
+
+          # release mode — latest release tag → PR with the release notes.
+          TAG="$(gh api "repos/$ENGINE_REPO/releases/latest" --jq .tag_name 2>/dev/null || true)"
+          [ -n "$TAG" ] || { echo "No releases published on $ENGINE_REPO yet — nothing to do."; exit 0; }
+          NEW_SHA="$(git ls-remote "$ENGINE_URL" "refs/tags/$TAG^{}" | cut -f1)"
+          [ -n "$NEW_SHA" ] || NEW_SHA="$(git ls-remote "$ENGINE_URL" "refs/tags/$TAG" | cut -f1)"
+          [ -n "$NEW_SHA" ] || { echo "::error::could not resolve tag $TAG"; exit 1; }
+          [ "$NEW_SHA" != "$CUR_SHA" ] || { echo "Engine pin already at $TAG — nothing to do."; exit 0; }
+          BRANCH="engine-$TAG"
+          if gh pr list --head "$BRANCH" --state open --json number --jq length | grep -qv '^0$'; then
+            echo "Update PR for $TAG already open — nothing to do."; exit 0
+          fi
+          git checkout -b "$BRANCH"
+          git update-index --cacheinfo "160000,$NEW_SHA,engine"
+          git commit -m "Engine update: $TAG"
+          git push -f origin "$BRANCH"
+          NOTES="$(gh api "repos/$ENGINE_REPO/releases/latest" --jq .body || echo "")"
+          URL="$(gh api "repos/$ENGINE_REPO/releases/latest" --jq .html_url || echo "")"
+          printf 'Engine update to **%s** (`%s`).\n\n%s\n\n---\nRelease: %s\nMerging deploys it. Roll back later by reverting this commit.\n' \
+            "$TAG" "${NEW_SHA:0:12}" "$NOTES" "$URL" > /tmp/pr-body.md
+          gh pr create --title "Engine update: $TAG" --body-file /tmp/pr-body.md --base main --head "$BRANCH"

package/templates/shell/health.yml

@@ -0,0 +1,233 @@
+name: Health canary
+
+# Deploy-path monitoring. Space content ships via `augur publish` into the bundle
+# store, not via pushes — so the failure worth catching is DRIFT: someone pushed
+# work to a space repo and nothing published it, and the live site quietly lags
+# what is in git. Nobody notices on their own, because everyone's own clone looks
+# right.
+#
+#   a. every space in the roster (deploy.config.json `spaces`): does the live
+#      /_build.json sha match the space repo's main HEAD? Drift older than a
+#      grace window = pushed-but-never-published (or a failed publish).
+#   b. a DIRTY publish that has outlived its window. Live content built from an
+#      uncommitted working tree exists in NO repository, so it cannot be rebuilt,
+#      reviewed or rolled forward. Fine for an hour of active work; not fine left
+#      standing.
+#   c. is AUGUR_PIN_TOKEN alive, if this shell uses one (roster-update.yml pushes
+#      with it)? Skipped when the secret is unset.
+#   d. is the site up at all? (implicit in (a)'s stamp fetch.)
+#   e. is this shell RUNNING what the engine's templates say it should be running?
+#      Same question as (a), one layer up — a fix that lands in templates/shell/ and
+#      never reaches the shells that already had a copy is invisible exactly the way
+#      publish drift is. Compared against the engine submodule, i.e. this shell's own
+#      pinned engine.
+#   g. is a gated path actually GATED? Nothing checked this until now, and (d) is why it
+#      needed its own check: /_build.json is a STATIC FILE, so a bare host with no worker
+#      running at all answers it correctly and this canary reports healthy. The probe asks
+#      for files that exist in the asset directory and must never be served — the roster
+#      at __config/instance.json, the worker, the modules it imports — and requires the
+#      answer not to BE those files. It matters most on a plain-Worker deploy, where the
+#      platform serves a matching asset before invoking the worker unless the config says
+#      otherwise, so this failure is one config line away and invisible to every other
+#      check here.
+#   f. is each space's BAKED chrome current with the serving engine? Page-level chrome
+#      (rail, overlays, layout) is baked at publish time (spaces.<id>.builtWithEngine),
+#      so an engine bump can leave a space serving older chrome than the deployed engine
+#      (engine.sha). deploy.yml nudges a re-bake and each space self-heals on a schedule;
+#      this catches the case where BOTH missed and the drift has outlived its window.
+#
+# On any failure the run exits non-zero (GitHub emails the owner) AND maintains a
+# single open issue labelled `health`; a green run closes it.
+#
+# SET BEFORE USE: SITE below. Secrets: SUBMODULE_PAT (Contents:read on every
+# space repo in the roster).
+
+on:
+  schedule:
+    - cron: "23 */6 * * *" # every 6 hours (offset minute — GitHub drops top-of-hour crons)
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write # create/comment/close the health issue with the default token
+
+concurrency:
+  group: health
+  cancel-in-progress: true
+
+jobs:
+  health:
+    runs-on: ubuntu-latest
+    env:
+      SITE: https://your-site-origin.example # ← your deploy.config.json siteOrigin
+      # NB: the `runner` context is not available in job-level env, so a literal path.
+      FAILS: /tmp/health-failures.txt
+      GRACE_SECONDS: "3600"        # 1h: a human or agent may publish minutes after pushing
+      DIRTY_GRACE_SECONDS: "21600" # 6h: an active session may legitimately sit dirty
+      REBAKE_GRACE_SECONDS: "28800" # 8h: > the space self-heal poll interval (6h), so (f)
+                                    # only fires once a re-bake has genuinely been missed
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The engine submodule is here for check (e) only — the roster is
+          # deploy.config.json and needs no checkout. It is the shell's OWN pinned
+          # engine, which is exactly the version its workflows should be compared to.
+          submodules: true
+          token: ${{ secrets.SUBMODULE_PAT }}
+          fetch-depth: 1
+
+      # (a)+(b) Live /_build.json sha vs each space repo's main HEAD. The stamp is
+      # written by `augur publish` (source sha + dirty flag + publishedAt), so
+      # equality means "what is in git is what is live". A recent push gets a grace
+      # window; so does a fresh working-tree publish, but only a window.
+      - name: Check live shas vs space repo HEADs (publish drift + dirty publishes)
+        env:
+          PAT: ${{ secrets.SUBMODULE_PAT }} # Contents:read on every space repo
+        run: |
+          set -euo pipefail
+          : > "$FAILS"
+          NOW=$(date -u +%s)
+          if ! STAMP="$(curl -fsS --max-time 30 "$SITE/_build.json")"; then
+            echo "could not fetch $SITE/_build.json — site down or stamp gone" >> "$FAILS"
+            exit 0
+          fi
+          jq -r '.spaces[]? | "\(.id) \(.repo)"' deploy.config.json | while read -r ID REPO; do
+            HEAD_SHA="$(GH_TOKEN="$PAT" gh api "repos/${REPO}/branches/main" --jq .commit.sha 2>/dev/null || true)"
+            if [ -z "$HEAD_SHA" ]; then
+              echo "cannot read ${REPO} main HEAD with SUBMODULE_PAT (token dead/expired, or repo access revoked?)" >> "$FAILS"
+              continue
+            fi
+            LIVE_SHA="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].sha // empty')"
+            DIRTY="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].dirty // false')"
+            if [ "$LIVE_SHA" = "$HEAD_SHA" ] && [ "$DIRTY" != "true" ]; then
+              echo "OK: $ID live sha matches main HEAD (${HEAD_SHA:0:12})"
+              continue
+            fi
+            PUSHED_AT="$(GH_TOKEN="$PAT" gh api "repos/${REPO}" --jq .pushed_at 2>/dev/null || true)"
+            AGE=$(( NOW - $(date -u -d "${PUSHED_AT:-1970-01-01T00:00:00Z}" +%s) ))
+            if [ "$DIRTY" = "true" ]; then
+              PUB_AT="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].publishedAt // empty')"
+              DIRTY_AGE=$(( NOW - $(date -u -d "${PUB_AT:-1970-01-01T00:00:00Z}" +%s) ))
+              if [ -n "$PUB_AT" ] && [ "$DIRTY_AGE" -le "$DIRTY_GRACE_SECONDS" ]; then
+                echo "OK: $ID live is a working-tree publish ${DIRTY_AGE}s ago — inside the ${DIRTY_GRACE_SECONDS}s window"
+              else
+                echo "dirty publish: $ID has been serving a working-tree publish (base ${LIVE_SHA:0:12}) for ${DIRTY_AGE}s — those exact bytes exist in NO repository. Commit the work and re-run \`augur publish\` from the $ID clone" >> "$FAILS"
+              fi
+              continue
+            fi
+            if [ "$AGE" -gt "$GRACE_SECONDS" ]; then
+              echo "publish drift: $ID main HEAD is ${HEAD_SHA:0:12} (pushed ${AGE}s ago) but live serves '${LIVE_SHA:-<absent>}' — pushed but never published; run \`augur publish\` from the $ID clone" >> "$FAILS"
+            else
+              echo "OK: $ID drifting but pushed ${AGE}s ago (inside the ${GRACE_SECONDS}s grace window)"
+            fi
+          done
+
+      # (f) Chrome-bake drift. engine.sha moves on every engine bump; a space's baked
+      # chrome (spaces.<id>.builtWithEngine) moves only when that space republishes. If a
+      # space is serving chrome older than the deployed engine and the drift has outlived
+      # REBAKE_GRACE_SECONDS (longer than the self-heal poll), the re-bake was missed.
+      - name: Check baked chrome vs the serving engine (re-bake drift)
+        run: |
+          set -uo pipefail
+          if ! STAMP="$(curl -fsS --max-time 30 "$SITE/_build.json")"; then
+            echo "no stamp — check (a) already recorded the site being down"; exit 0
+          fi
+          NOW=$(date -u +%s)
+          ENG="$(printf '%s' "$STAMP" | jq -r '.engine.sha // empty')"
+          if [ -z "$ENG" ]; then echo "no engine.sha in stamp — skipping (f)"; exit 0; fi
+          ENG_AT="$(printf '%s' "$STAMP" | jq -r '.engine.publishedAt // empty')"
+          ENG_AGE=$(( NOW - $(date -u -d "${ENG_AT:-1970-01-01T00:00:00Z}" +%s) ))
+          jq -r '.spaces[]? | "\(.id) \(.repo)"' deploy.config.json | while read -r ID REPO; do
+            BW="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].builtWithEngine // empty')"
+            DIRTY="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].dirty // false')"
+            if [ "$BW" = "$ENG" ]; then echo "OK: $ID baked chrome matches serving engine (${ENG:0:12})"; continue; fi
+            if [ "$DIRTY" = "true" ]; then echo "OK: $ID is a working-tree publish — chrome catches up when it republishes"; continue; fi
+            if [ "$ENG_AGE" -le "$REBAKE_GRACE_SECONDS" ]; then
+              echo "OK: $ID chrome ${BW:-<none>} vs engine ${ENG:0:12}, but engine deployed only ${ENG_AGE}s ago (grace)"; continue
+            fi
+            if [ -z "$BW" ]; then
+              echo "chrome drift: $ID has no builtWithEngine stamp ${ENG_AGE}s after the engine deployed — never re-baked; the shell's space-rebake should have converged this (check the 'Space re-bake' and 'Deploy site' runs), or run: gh workflow run space-rebake.yml" >> "$FAILS"
+            else
+              echo "chrome drift: $ID serves baked chrome ${BW:0:12} but the engine is ${ENG:0:12} (deployed ${ENG_AGE}s ago) — the re-bake was missed; the shell's space-rebake should have converged this (check the 'Space re-bake' and 'Deploy site' runs), or run: gh workflow run space-rebake.yml" >> "$FAILS"
+            fi
+          done
+
+      # (g) Front-door integrity. The one check here that would notice the site serving
+      # its own roster to strangers. Skips gracefully on an engine pinned before the probe
+      # existed, same as (e), so bumping the engine is what turns it on.
+      - name: Check a gated path is gated (front-door parity)
+        run: |
+          set -uo pipefail
+          if [ ! -f engine/scripts/frontdoor-parity.mjs ]; then
+            echo "pinned engine predates frontdoor-parity — skipping (bump the engine to enable)"; exit 0
+          fi
+          if ! OUT="$(node engine/scripts/frontdoor-parity.mjs "$SITE" 2>&1)"; then
+            echo "$OUT"
+            echo "front door: a path that must be decided by the worker was answered by the platform instead — see the run log for which. If this instance is on a plain Worker, check run_worker_first = true in wrangler.toml" >> "$FAILS"
+          else
+            echo "$OUT"
+          fi
+
+      # (c) AUGUR_PIN_TOKEN — only shells that wired roster write-back (or another
+      # push-must-retrigger-CI workflow) have one. Unset = nothing to monitor.
+      - name: Validate AUGUR_PIN_TOKEN
+        env:
+          GH_TOKEN: ${{ secrets.AUGUR_PIN_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [ -z "${GH_TOKEN:-}" ]; then echo "AUGUR_PIN_TOKEN not configured — skipping"; exit 0; fi
+          if ! gh api "repos/${GITHUB_REPOSITORY}" --jq .full_name >/dev/null 2>&1; then
+            echo "AUGUR_PIN_TOKEN is dead/expired — workflows that push cannot retrigger CI (regenerate the PAT and update the secret)" >> "$FAILS"
+          else
+            echo "OK: AUGUR_PIN_TOKEN authenticates"
+          fi
+
+      # (e) Template drift. Same shape as (a): compare what is RUNNING against what the
+      # source of truth says. Only behavioural divergence fails — a reworded comment or
+      # a filled-in placeholder is expected and stays quiet.
+      - name: Check workflows against the engine's templates
+        run: |
+          set -uo pipefail
+          if [ ! -f engine/scripts/shell-lint.mjs ]; then
+            echo "pinned engine predates shell-lint — skipping (bump the engine to enable)"; exit 0
+          fi
+          if ! OUT="$(node engine/scripts/shell-lint.mjs 2>&1)"; then
+            echo "$OUT"
+            echo "workflow drift: this shell is not running what its pinned engine's templates/shell/ says it should — see the run log for the diverging lines" >> "$FAILS"
+          else
+            echo "$OUT"
+          fi
+
+      # Report — one issue, not a pile: create-or-comment on the single open
+      # `health` issue on failure (+ exit 1 so GitHub emails the owner); close it
+      # on recovery.
+      - name: Report — maintain the health issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          gh label create health --color D93F0B --description "Deploy-path canary failures (health.yml)" 2>/dev/null || true
+          EXISTING="$(gh issue list --label health --state open --json number --jq '.[0].number // empty')"
+          if [ -s "$FAILS" ]; then
+            N="$(wc -l < "$FAILS" | tr -d ' ')"
+            FIRST="$(head -n1 "$FAILS" | cut -c1-100)"
+            if [ "$N" -gt 1 ]; then TITLE="🚨 Health: $N checks failing"; else TITLE="🚨 Health: $FIRST"; fi
+            BODY="$(printf 'Canary run: %s\n\nFailing checks:\n%s\n\n(Auto-maintained by health.yml — this issue closes itself when a run goes green.)' "$RUN_URL" "$(sed 's/^/- /' "$FAILS")")"
+            if [ -n "$EXISTING" ]; then
+              gh issue edit "$EXISTING" --title "$TITLE" >/dev/null
+              gh issue comment "$EXISTING" --body "$BODY" >/dev/null
+              echo "Updated open issue #$EXISTING"
+            else
+              gh issue create --title "$TITLE" --body "$BODY" --label health >/dev/null
+              echo "Opened a new health issue"
+            fi
+            echo "::error::health checks failing:"; sed 's/^/  - /' "$FAILS"
+            exit 1
+          fi
+          echo "All health checks green."
+          if [ -n "$EXISTING" ]; then
+            gh issue close "$EXISTING" --comment "All health checks green again — closing. ($RUN_URL)" >/dev/null
+            echo "Closed recovered issue #$EXISTING"
+          fi

package/templates/shell/kv-backup.yml

@@ -0,0 +1,201 @@
+name: KV backup (review archive)
+
+# Nightly export of the production KV namespace — the comment/annotation threads,
+# dev statuses, pins, renames and canvas state that make up the team's review
+# decision record. KV is the ONLY copy (Cloudflare has no point-in-time restore
+# for KV), so a bad write / bulk delete / account mishap would be unrecoverable
+# without this.
+#
+# This is the OTHER half of the backup story, and it does not overlap with
+# store-backup.yml: that one copies published CONTENT out of the bundle store
+# (R2); this one copies the mutable state the worker accumulates around it.
+# A shell needs both. Neither covers the other.
+#
+# The export lists every key (paginated), GETs each raw value, assembles one JSON
+# object {key: value}, and commits it to the orphan `kv-backups` branch as
+# backup-YYYY-MM-DD.json plus latest.json, pruning dated files older than 30 days.
+# The branch is created by this workflow on first run. Restore = read the JSON,
+# PUT each pair back via the same API.
+#
+# ⚠️ A KV VALUE IS BYTES, NOT TEXT, and that distinction cost this job every canvas
+# board image it ever copied. `jq --rawfile` carries a value as a JSON string, and a
+# JSON string carries TEXT: every byte sequence that is not valid UTF-8 became U+FFFD
+# on the way in and no restore could bring it back. Board images are stored raw under
+# `basset:<sha256-prefix>`, so the copy came back LONGER than the original, different,
+# and no longer matching the checksum in its own key name — confidently wrong rather
+# than visibly missing. So each value is round-tripped through jq and COMPARED with the
+# bytes that came off the wire; anything that does not survive is carried as
+# {"b64": "…"} instead. A value that is text is still a plain string, so a copy taken
+# before this existed and one taken after are read by the same restore. Do not
+# "simplify" the comparison away.
+#
+# ⚠️ THE SHELL REPO MUST BE PRIVATE. This export is the whole namespace, and the
+# namespace holds `users:secrets` (PBKDF2 password hashes, and the tombstones that
+# hold reset passwords out of service) and `publish:tokens` (live bearer tokens
+# that can overwrite published content). Committing that to a public repo hands
+# over the instance. Do not enable this workflow on a public shell.
+#
+# Secrets: CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID (the same ones deploy.yml
+# uses) + AUGUR_KV_NS (the KV namespace id this instance's worker is bound to).
+
+on:
+  schedule:
+    - cron: "0 3 * * *" # nightly, 03:00 UTC
+  workflow_dispatch: # allow manual runs from the Actions tab
+
+permissions:
+  contents: write # push the backup commit to the kv-backups branch
+
+concurrency:
+  group: kv-backup
+  cancel-in-progress: false
+
+jobs:
+  backup:
+    runs-on: ubuntu-latest
+    steps:
+      # ⛔ REFUSE TO RUN ON A PUBLIC REPOSITORY. First step, on purpose.
+      #
+      # A COMMENT IS NOT A GUARD, AND THIS HAS ALREADY HAPPENED. A public fork of the
+      # engine ran a workflow of this shape and published a full production KV export of
+      # a live instance — 58 keys, 26 internal comment threads, five real names and
+      # personal addresses — reachable with no authentication. GitHub shares git objects
+      # across a fork network, so the commit resolved through the PARENT repository's own
+      # raw URL: deleting the branch, deleting the fork and rewriting the parent's history
+      # all leave it fetchable, and only a GitHub Support object purge closes it. The
+      # header above this job said "the shell repo must be private" the whole time.
+      #
+      # IT FAILS, IT DOES NOT SKIP. A skip is worse than having no backup workflow at all,
+      # because the operator goes on believing a backup exists.
+      #
+      # AND IT FAILS WHEN IT CANNOT TELL. `github.event.repository.private` is absent on
+      # some event types, and an absent value is not a private repository — it is an
+      # unanswered question, and this is the one question that must not have a default.
+      - name: Refuse to run on a public repository
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CTX_PRIVATE: ${{ github.event.repository.private }}
+        run: |
+          set -uo pipefail
+          PRIVATE="$(gh api "repos/${GITHUB_REPOSITORY}" --jq .private 2>/dev/null || true)"
+          if [ -z "$PRIVATE" ]; then PRIVATE="${CTX_PRIVATE:-}"; fi
+          case "$PRIVATE" in
+            true)
+              echo "OK: ${GITHUB_REPOSITORY} is private"
+              ;;
+            false)
+              echo "::error::REFUSING TO RUN: ${GITHUB_REPOSITORY} is a PUBLIC repository. This job exports the instance's whole state and writes it into this repo. On a public repo that publishes it to anyone, permanently — a fork network keeps the objects fetchable through the parent's URL after the branch, the fork and the history are all gone. Make the repository private, or delete this workflow."
+              exit 1
+              ;;
+            *)
+              echo "::error::REFUSING TO RUN: could not determine whether ${GITHUB_REPOSITORY} is private (got '${PRIVATE}'). An unanswered question is not a private repository."
+              exit 1
+              ;;
+          esac
+
+      - uses: actions/checkout@v4 # main — the kv-backups branch is fetched/created below
+
+      # Export the whole namespace to one JSON object. The namespace is small
+      # (hundreds of keys), so a plain sequential loop is fine — no rate-limit
+      # dance needed.
+      - name: Export KV namespace
+        env:
+          CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CF_KV_NS: ${{ secrets.AUGUR_KV_NS }}
+        run: |
+          set -euo pipefail
+          if [ -z "${CF_KV_NS:-}" ]; then
+            echo "::error::AUGUR_KV_NS is not configured — set it to this instance's KV namespace id."; exit 1
+          fi
+          BASE="https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/storage/kv/namespaces/${CF_KV_NS}"
+          AUTH=(-H "Authorization: Bearer ${CF_API_TOKEN}")
+          WORK="${RUNNER_TEMP}/kv"
+          mkdir -p "$WORK/objs"
+
+          # 1) List all keys (cursor-paginated, 1000/page).
+          : > "$WORK/keys.txt"
+          CURSOR=""
+          while :; do
+            URL="${BASE}/keys?limit=1000"
+            [ -n "$CURSOR" ] && URL="${URL}&cursor=${CURSOR}"
+            RESP="$(curl -fsS --max-time 60 "${AUTH[@]}" "$URL")"
+            printf '%s' "$RESP" | jq -e .success >/dev/null # hard-fail on an API error envelope
+            printf '%s' "$RESP" | jq -r '.result[].name' >> "$WORK/keys.txt"
+            CURSOR="$(printf '%s' "$RESP" | jq -r '.result_info.cursor // empty')"
+            [ -z "$CURSOR" ] && break
+          done
+          COUNT="$(wc -l < "$WORK/keys.txt" | tr -d ' ')"
+          echo "Listed $COUNT keys."
+          if [ "$COUNT" -eq 0 ]; then
+            echo "::error::namespace listed ZERO keys — wrong namespace id, or the data is gone; refusing to write an empty backup."; exit 1
+          fi
+
+          # 2) GET each raw value, wrap it as a single-pair object, then merge all pairs.
+          I=0
+          BIN=0
+          while IFS= read -r KEY; do
+            ENC="$(jq -rn --arg k "$KEY" '$k|@uri')"
+            if ! curl -fsS --max-time 60 "${AUTH[@]}" -o "$WORK/value" "${BASE}/values/${ENC}"; then
+              echo "::warning::key vanished/failed mid-export, skipped: $KEY"; continue
+            fi
+            OUT="$WORK/objs/$(printf '%08d' "$I").json"
+            # >>> value-encode (the engine's test/kv-backup-workflow.test.mjs extracts and
+            # runs exactly these lines against a real PNG — keep them self-contained, and
+            # keep them using only $KEY, $WORK and $OUT.)
+            #
+            # Ask the bytes, do not assume: write the string form, read it back out with
+            # `jq -j` (raw, no trailing newline) and compare with cmp. Equal means the
+            # value is text and rides as a string, exactly as it always has. Anything else
+            # — a JPEG, a PNG, a lone invalid byte — rides as {"b64": "…"} and comes back
+            # byte for byte. `tr -d '\n'` rather than `base64 -w0`: -w is GNU-only.
+            if jq -n --arg k "$KEY" --rawfile v "$WORK/value" '{($k): $v}' > "$WORK/one.json" 2>/dev/null \
+               && jq -j --arg k "$KEY" '.[$k]' "$WORK/one.json" > "$WORK/back" 2>/dev/null \
+               && cmp -s "$WORK/value" "$WORK/back"; then
+              mv "$WORK/one.json" "$OUT"
+            else
+              base64 < "$WORK/value" | tr -d '\n' > "$WORK/b64"
+              jq -n --arg k "$KEY" --rawfile b "$WORK/b64" '{($k): {b64: ($b|rtrimstr("\n"))}}' > "$OUT"
+              BIN=$((BIN+1))
+            fi
+            # <<< value-encode
+            I=$((I+1))
+          done < "$WORK/keys.txt"
+          jq -s 'add' "$WORK"/objs/*.json > "$WORK/backup.json"
+          echo "Exported $(jq 'length' "$WORK/backup.json") key/value pairs ($BIN carried as base64 — values that are not UTF-8 text)."
+
+      # Commit to the orphan kv-backups branch (created here on first run), pruning
+      # dated backups older than 30 days. latest.json always mirrors today's file.
+      - name: Commit to kv-backups branch
+        run: |
+          set -euo pipefail
+          WORK="${RUNNER_TEMP}/kv"
+          git config user.name "augur-bot"
+          git config user.email "augur-bot@users.noreply.github.com"
+          if git fetch origin kv-backups 2>/dev/null; then
+            git checkout -B kv-backups FETCH_HEAD
+          else
+            echo "No kv-backups branch yet — creating the orphan."
+            git checkout --orphan kv-backups
+            git rm -rfq .
+            git clean -fdq
+          fi
+          TODAY="$(date -u +%F)"
+          cp "$WORK/backup.json" "backup-${TODAY}.json"
+          cp "$WORK/backup.json" latest.json
+          git add "backup-${TODAY}.json" latest.json
+          # Prune dated files older than 30 days (lexicographic compare works on YYYY-MM-DD).
+          CUTOFF="$(date -u -d '30 days ago' +%F)"
+          for F in backup-*.json; do
+            D="${F#backup-}"; D="${D%.json}"
+            if [[ "$D" < "$CUTOFF" ]]; then
+              git rm -q "$F"
+              echo "Pruned $F (older than $CUTOFF)"
+            fi
+          done
+          if git diff --cached --quiet; then
+            echo "Nothing changed since the last backup — no commit."
+            exit 0
+          fi
+          git commit -m "KV backup ${TODAY} ($(jq 'length' latest.json) keys)"
+          git push origin kv-backups