Add GT_BYPASS_KEY for unlimited submissions + dry mode

X-Bypass-Key header matching GT_BYPASS_KEY env (compared via hmac.compare_digest)
unlocks two things:
- skip the IP/day quota gate
- with form param dry=1, score against GT but skip the leaderboard insert
(and skip the submission archive)

graphtestbed/submit.py reads GRAPHTESTBED_BYPASS_KEY env and sends X-Bypass-Key
on every POST when set; --server-dry CLI flag toggles dry=1.

push_to_space.sh now overlays server/space/Dockerfile at root in addition to
README (HF Docker SDK looks for Dockerfile at the repo root).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

graphtestbed/submit.py

@@ -64,7 +64,10 @@ def validate_submission(task: str, csv_path: Path) -> dict:
     }
 
 
-def submit(task: str, csv_path: Path, agent: str, dry_run: bool = False) -> None:
+def submit(
+    task: str, csv_path: Path, agent: str,
+    dry_run: bool = False, server_dry: bool = False,
+) -> None:
     info = validate_submission(task, csv_path)
     print(f"✓ Schema OK   (rows={info['n_rows']}, sha256={info['sha256'][:12]}...)")
 
@@ -78,13 +81,29 @@ def submit(task: str, csv_path: Path, agent: str, dry_run: bool = False) -> None
     except ImportError:
         raise SystemExit("Missing dependency: pip install requests")
 
-    print(f"  → POST {API_URL}/submit  task={task} agent={agent}")
+    headers = {}
+    bypass_key = os.environ.get("GRAPHTESTBED_BYPASS_KEY", "").strip()
+    if bypass_key:
+        headers["X-Bypass-Key"] = bypass_key
+    elif server_dry:
+        raise SystemExit(
+            "--server-dry needs GRAPHTESTBED_BYPASS_KEY exported (the server "
+            "will only honor dry mode for clients holding the bypass key)."
+        )
+
+    data = {"task": task, "agent": agent}
+    if server_dry:
+        data["dry"] = "1"
+
+    print(f"  → POST {API_URL}/submit  task={task} agent={agent}"
+          f"{' [bypass]' if bypass_key else ''}{' [dry]' if server_dry else ''}")
     try:
         with csv_path.open("rb") as f:
             resp = requests.post(
                 f"{API_URL}/submit",
-                data={"task": task, "agent": agent},
+                data=data,
                 files={"file": (csv_path.name, f, "text/csv")},
+                headers=headers,
                 timeout=TIMEOUT_SEC,
             )
     except requests.exceptions.ConnectionError as e:
@@ -124,8 +143,12 @@ def main() -> None:
                     help="Identifier for this agent (e.g. autopipe-v0.4)")
     ap.add_argument("--dry-run", action="store_true",
                     help="Validate schema locally, don't POST")
+    ap.add_argument("--server-dry", action="store_true",
+                    help="Score on the server but don't insert into the "
+                         "leaderboard. Requires GRAPHTESTBED_BYPASS_KEY.")
     args = ap.parse_args()
-    submit(args.task, args.file, args.agent, dry_run=args.dry_run)
+    submit(args.task, args.file, args.agent,
+           dry_run=args.dry_run, server_dry=args.server_dry)
 
 
 if __name__ == "__main__":

server/api.py

@@ -50,6 +50,7 @@ MANIFEST_PATH = Path(os.environ.get(
     Path(__file__).resolve().parents[1] / "datasets" / "manifest.yaml",
 ))
 QUOTA_PER_DAY = int(os.environ.get("GT_QUOTA", "5"))
+BYPASS_KEY = os.environ.get("GT_BYPASS_KEY", "").strip() or None
 MAX_UPLOAD_BYTES = 50 * 1024 * 1024  # 50 MB hard cap
 
 
@@ -154,6 +155,14 @@ def submit():
     file = request.files.get("file")
     ip = request.headers.get("X-Forwarded-For", request.remote_addr or "unknown")
 
+    # Bypass: maintainer/CI key skips quota and (optionally with dry=1) the
+    # leaderboard insert. Compared with hmac.compare_digest to avoid timing
+    # leaks against the hex-string secret.
+    sent_key = request.headers.get("X-Bypass-Key", "").strip()
+    bypass = bool(BYPASS_KEY and sent_key
+                  and __import__("hmac").compare_digest(sent_key, BYPASS_KEY))
+    dry = bypass and request.form.get("dry") == "1"
+
     if not (task and agent and file):
         return jsonify({"error": "form fields required: task, agent, file"}), 400
 
@@ -162,12 +171,15 @@ def submit():
         return jsonify({"error": f"unknown task '{task}'", "known": sorted(manifest)}), 404
     cfg = manifest[task]
 
-    quota = _quota_remaining(task, ip)
-    if quota <= 0:
-        return jsonify({
-            "error": f"quota exceeded ({QUOTA_PER_DAY}/day per IP per task)",
-            "task": task,
-        }), 429
+    if bypass:
+        quota = -1
+    else:
+        quota = _quota_remaining(task, ip)
+        if quota <= 0:
+            return jsonify({
+                "error": f"quota exceeded ({QUOTA_PER_DAY}/day per IP per task)",
+                "task": task,
+            }), 429
 
     raw = file.read()
     sub_sha = hashlib.sha256(raw).hexdigest()
@@ -192,21 +204,22 @@ def submit():
     run_id = uuid.uuid4().hex[:12]
     now = dt.datetime.now(dt.timezone.utc).isoformat()
     conn = _db()
-    conn.execute(
-        "INSERT INTO submissions VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        (run_id, task, agent, scored["primary"],
-         json.dumps(scored["secondary"]), sub_sha, scored["n_rows"], ip, now),
-    )
-    conn.commit()
+    if not dry:
+        conn.execute(
+            "INSERT INTO submissions VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (run_id, task, agent, scored["primary"],
+             json.dumps(scored["secondary"]), sub_sha, scored["n_rows"], ip, now),
+        )
+        conn.commit()
 
-    # Archive the raw CSV when GT_ARCHIVE_DIR is configured, so the deploy
-    # host can later prove what each scored entry was. Filename embeds the
-    # agent + run_id so multiple submissions don't collide.
-    if ARCHIVE_DIR is not None:
-        safe_agent = "".join(c if c.isalnum() or c in "-_." else "_" for c in agent)
-        out = ARCHIVE_DIR / task / f"{safe_agent}-{run_id}.csv"
-        out.parent.mkdir(parents=True, exist_ok=True)
-        out.write_bytes(raw)
+        # Archive the raw CSV when GT_ARCHIVE_DIR is configured, so the deploy
+        # host can later prove what each scored entry was. Filename embeds the
+        # agent + run_id so multiple submissions don't collide.
+        if ARCHIVE_DIR is not None:
+            safe_agent = "".join(c if c.isalnum() or c in "-_." else "_" for c in agent)
+            out = ARCHIVE_DIR / task / f"{safe_agent}-{run_id}.csv"
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_bytes(raw)
 
     # Rank = how many distinct agents have a strictly better best-score on
     # this task. The just-inserted row contributes to that count only if the
@@ -231,7 +244,9 @@ def submit():
         "secondary": scored["secondary"],
         "n_rows": scored["n_rows"],
         "leaderboard_rank": rank,
-        "quota_remaining": quota - 1,
+        "quota_remaining": "unlimited" if bypass else (quota - 1),
+        "bypass": bypass,
+        "dry": dry,
         "submitted_at": now,
     })
 

server/space/README.md

@@ -43,6 +43,7 @@ Test labels live only in the companion private dataset repo
 | `GT_DATASET_REPO` | no | `lanczos/graphtestbed-gt` | private dataset holding GT + leaderboard backups |
 | `GT_BACKUP_INTERVAL` | no | `60` | seconds between sqlite → dataset-repo pushes |
 | `GT_QUOTA` | no | `5` | submissions/day/IP/task |
+| `GT_BYPASS_KEY` | no | — | shared secret; clients sending it as `X-Bypass-Key` header skip quota and may pass `dry=1` to score without inserting |
 
 ## Persistence
 

server/space/push_to_space.sh

@@ -18,9 +18,12 @@ trap 'git checkout "$BRANCH" >/dev/null 2>&1 || true; \
       git branch -D "$TEMP" >/dev/null 2>&1 || true' EXIT
 
 git checkout -b "$TEMP"
+# HF Docker SDK looks for Dockerfile at the repo root; our canonical copy
+# lives in server/space/. Overlay both for the deploy.
 cp server/space/README.md README.md
-git add README.md
-git commit --no-verify -m "deploy: overlay server/space/README.md as Space root"
+cp server/space/Dockerfile Dockerfile
+git add README.md Dockerfile
+git commit --no-verify -m "deploy: overlay server/space/{README,Dockerfile} at root"
 git push -f space "$TEMP:main"
 echo
 echo "pushed to space/main"