fix: stop the nightly sync from committing timestamp-only diffs

The job committed every night even when upstream had not moved: synced_at
in UPSTREAM.json was rewritten on every run, and build_index.py stamped
generated_at from the current clock, so the staged diff was never empty
and the git diff --quiet guard never fired.

sync_upstream.sh now leaves UPSTREAM.json alone when the fetched upstream
commit matches the recorded one, and generated_at is derived from
synced_at instead of now(). A night with no upstream activity produces a
genuinely empty diff. Adds a regression test and documents the reasoning
in WORKFLOW.md.

Also pins the one-time correction to data/tonies.json.

Author: claude

data/tonies.json

@@ -76,6 +76,20 @@ runs on a schedule (02:27 UTC nightly) and can also be triggered manually:
    `github-actions[bot]` with a message naming the upstream short SHA and
    file count, and pushes directly to the branch the workflow runs on.
 
+"Nothing changed" is meant literally, which takes some care with timestamps:
+
+* `sync_upstream.sh` leaves `data/UPSTREAM.json` untouched when the upstream
+  commit it just fetched matches the one already recorded. Rewriting
+  `synced_at` on every run would make the file differ every night even when
+  the mirror is identical.
+* `build_index.py` takes `generated_at` from that `synced_at` rather than
+  from the current clock, so `data/tonies.json` and `TONIES.md` inherit the
+  same property.
+
+Together this means a night with no upstream activity produces a genuinely
+empty diff and therefore no commit. `tests/test_build_index.py` guards the
+second half of this.
+
 Triggering it manually (e.g. from the Actions tab, "Run workflow") accepts a
 `dry_run` input: when true, the sync and index rebuild still run, but the
 commit step only prints what it *would* commit (`git diff --cached --stat`)

docs/WORKFLOW.md

@@ -74,20 +74,36 @@ def collect_entries(tonies_dir: Path) -> list[dict]:
     return entries
 
 
-def load_upstream_commit() -> str:
+def load_upstream() -> dict:
+    """Read data/UPSTREAM.json, tolerating a missing or corrupt file."""
     if not UPSTREAM_JSON.exists():
-        return "unknown"
+        return {}
     try:
-        data = json.loads(UPSTREAM_JSON.read_text(encoding="utf-8"))
+        return json.loads(UPSTREAM_JSON.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
-        return "unknown"
-    commit = data.get("commit", "unknown")
+        return {}
+
+
+def load_upstream_commit() -> str:
+    commit = load_upstream().get("commit", "unknown")
     return commit[:7] if commit != "unknown" else commit
 
 
+def load_synced_at() -> str:
+    """Timestamp of the last upstream sync.
+
+    Deliberately not "now": the generated files must be byte-identical when
+    the upstream mirror has not moved, otherwise the nightly job commits a
+    timestamp-only diff every single night.
+    """
+    return load_upstream().get(
+        "synced_at", datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    )
+
+
 def build_tonies_json_payload(entries: list[dict], upstream_commit: str) -> dict:
     return {
-        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "generated_at": load_synced_at(),
         "upstream_commit": upstream_commit,
         "count": len(entries),
         "tonies": entries,
@@ -187,12 +203,7 @@ def render_tonies_md(
 
 def write_tonies_md(entries: list[dict]) -> None:
     upstream_commit = load_upstream_commit()
-    synced_at = "unknown"
-    if UPSTREAM_JSON.exists():
-        try:
-            synced_at = json.loads(UPSTREAM_JSON.read_text(encoding="utf-8")).get("synced_at", "unknown")
-        except (json.JSONDecodeError, OSError):
-            pass
+    synced_at = load_upstream().get("synced_at", "unknown")
     TONIES_MD.write_text(render_tonies_md(entries, upstream_commit, synced_at), encoding="utf-8")
 
 

scripts/build_index.py

@@ -56,6 +56,7 @@ AFTER_COUNT="$(find "$DEST_DIR" -name '*.nfc' | wc -l | tr -d ' ')"
 
 python3 - "$UPSTREAM_JSON" "$UPSTREAM_URL" "$UPSTREAM_BRANCH" "$COMMIT_SHA" "$COMMIT_DATE" "$SYNCED_AT" "$AFTER_COUNT" <<'PYEOF'
 import json
+import os
 import sys
 
 out_path, repository, branch, commit, commit_date, synced_at, file_count = sys.argv[1:8]
@@ -69,6 +70,24 @@ data = {
     "file_count": int(file_count),
 }
 
+# Only rewrite the file when the mirror actually moved. "synced_at" changes on
+# every run by definition, so writing it unconditionally would produce a
+# timestamp-only diff -- and therefore a pointless commit -- every night.
+# Everything else in the record is derived from the upstream commit, so an
+# unchanged SHA means an unchanged mirror.
+if os.path.exists(out_path):
+    try:
+        with open(out_path, encoding="utf-8") as f:
+            previous = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        previous = None
+
+    if previous is not None:
+        comparable = {k: v for k, v in data.items() if k != "synced_at"}
+        if all(previous.get(k) == v for k, v in comparable.items()):
+            print("Upstream unchanged, keeping existing UPSTREAM.json", file=sys.stderr)
+            sys.exit(0)
+
 with open(out_path, "w", encoding="utf-8") as f:
     json.dump(data, f, indent=2, ensure_ascii=False)
     f.write("\n")

scripts/sync_upstream.sh

@@ -86,6 +86,31 @@ def test_json_payload_shape(self):
         self.assertIn("generated_at", payload)
         json.dumps(payload)  # must be JSON-serializable
 
+    def test_generated_at_tracks_the_sync_not_the_clock(self):
+        """Two builds must be byte-identical while the mirror has not moved.
+
+        Regression guard: deriving generated_at from datetime.now() made the
+        nightly job commit a timestamp-only diff every single night.
+        """
+        entries = build_index.collect_entries(self.tonies_dir)
+        upstream = {
+            "commit": "e6f8fd419bed396be9575930412da9a0e2d7a6cc",
+            "synced_at": "2026-08-02T17:17:01Z",
+        }
+        upstream_json = Path(self.tmp) / "UPSTREAM.json"
+        upstream_json.write_text(json.dumps(upstream), encoding="utf-8")
+
+        original = build_index.UPSTREAM_JSON
+        build_index.UPSTREAM_JSON = upstream_json
+        try:
+            first = build_index.build_tonies_json_payload(entries, "e6f8fd4")
+            second = build_index.build_tonies_json_payload(entries, "e6f8fd4")
+        finally:
+            build_index.UPSTREAM_JSON = original
+
+        self.assertEqual(first["generated_at"], upstream["synced_at"])
+        self.assertEqual(json.dumps(first), json.dumps(second))
+
     def test_duplicate_uid_detection(self):
         entries = build_index.collect_entries(self.tonies_dir)
         dupes = build_index.find_duplicate_uids(entries)