ci: deploy game_server (a9efbe759359)

README.package.md

@@ -33,6 +33,12 @@ Optional: copy **`.env.example`** to **`server/.env`** so local runs pick up **`
 | `FEATURE_GUESSES_RECORD` / `NUTONIC_FEATURE_GUESSES_RECORD` | No | Default **`false`**. When **`true`**, enables **`POST /api/v1/maps/{map_id}/guesses/record`** and sets `features.guesses_record` on **`GET /api/v1/config`**. Use **`true`** in local dev when exercising telemetry (`rules/05`, `docs/GAME-ENGINE.md` §12.3). |
 | `NUTONIC_GUESS_TELEMETRY_DATABASE_URL` | No | Default `sqlite:///data/nutonic_guess_telemetry.db`. SQLite file for optional guess rows (created under `data/` like the leaderboard DB). |
 | `NUTONIC_RANKED_DATABASE_URL` | No | Default `sqlite:///data/nutonic_ranked.db`. SQLite for ranked round rows (**IMP-090**). |
+| `NUTONIC_HF_PERSISTENCE_ENABLED` / `HF_PERSISTENCE_ENABLED` | No | Default **`false`**. When **`true`**, SQLite stores bootstrap from and sync writes to a Hugging Face Dataset repo. |
+| `NUTONIC_HF_PERSISTENCE_REQUIRED` / `HF_PERSISTENCE_REQUIRED` | No | Default **`false`**. When **`true`** with HF persistence enabled, startup fails if repo id/token is missing and runtime fails on sync errors (fail-fast mode). |
+| `NUTONIC_HF_PERSISTENCE_REPO_ID` / `HF_PERSISTENCE_REPO_ID` | No | Dataset repo id (`owner/name`) used for persisted SQLite files. |
+| `NUTONIC_HF_PERSISTENCE_SUBDIR` / `HF_PERSISTENCE_SUBDIR` | No | Default `server-persistence`. Subdirectory inside the dataset repo for DB files. |
+| `NUTONIC_HF_PERSISTENCE_STARTUP_PULL_MODE` / `HF_PERSISTENCE_STARTUP_PULL_MODE` | No | Default `if_missing`. `if_missing` only pulls when local DB is absent; `always` always pulls from dataset at startup (remote wins). |
+| `HF_API_WRITE` / `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` | No | Hub token used by HF persistence sync client for dataset read/write calls. Prefer a dedicated write token in production. |
 | `NUTONIC_RANKED_STALE_OPEN_ROUND_MAX_AGE_SECONDS` | No | Default **604800** (7d). Abandoned **`open`** ranked rounds older than this are deleted on each **`POST /api/v1/ranked/rounds/start`** (housekeeping). |
 | `NUTONIC_EXPOSE_MANIFEST_ROUND_TRUTH` | No | Default **`false`**: **`GET /api/v1/cache/manifest`** omits `locations` and `ai_guesses` (public spoiler hygiene). Set **`true`** for local dev / tests that need full fixture slices. |
 | `NUTONIC_MANIFEST_FULL_PATH` / `MANIFEST_FULL_PATH` | No | When set to an existing **`manifest.full.json`** (same schema as **`assemble_manifest.py`** output), replaces the builtin demo **`PUBLISHED_MAPS` / `MANIFEST_LOCATIONS` / `MANIFEST_AI_GUESSES`** at process start so **`GET /api/v1/maps`**, **`GET /api/v1/cache/manifest`**, and **`POST /api/v1/ranked/rounds/start`** use the full GeoGuessr-derived catalog. Optional **`satellite_caption_sidecar`** on each location is preserved and echoed on **`RankedClueOut`** when present. |
@@ -64,6 +70,7 @@ The game server is deployed by **`.github/workflows/huggingface-deploy.yml`**, n
 | Runtime profile | `tools/hf_deploy/profiles/game_server.yaml`: `cpu-basic`, `FEATURE_RANKED=false`, `FEATURE_COMMUNITY_LB_POST=false`, `FEATURE_PRO_JOBS=false`, `NUTONIC_EXPOSE_MANIFEST_ROUND_TRUTH=false`. |
 | Hub auth | `HF_TOKEN_NUTONIC`, then `HF_TOKEN`, then `HF_API_WRITE`. |
 | Runtime secrets | `NUTONIC_JWT_SECRET` is pushed to the Space as `JWT_SECRET`; `NUTONIC_LEADERBOARD_DATABASE_URL` and `NUTONIC_RANKED_DATABASE_URL` are pushed under the same names when set. |
+| HF dataset persistence wiring | `NUTONIC_HF_PERSISTENCE_ENABLED`, `NUTONIC_HF_PERSISTENCE_REQUIRED`, `NUTONIC_HF_PERSISTENCE_REPO_ID`, `NUTONIC_HF_PERSISTENCE_SUBDIR`, and `NUTONIC_HF_PERSISTENCE_STARTUP_PULL_MODE` are forwarded as runtime variables; `NUTONIC_HF_PERSISTENCE_TOKEN` is pushed as `HF_API_WRITE` secret for dataset writes. |
 | Post-deploy smoke | `python tools/live_inference_smoke.py --preset game-deploy --timeout 30 --strict --json-report-path artifacts/hf-smoke-game.json`. |
 
 The deployed Space defaults are intentionally conservative: ranked, community writes, PRO jobs, and manifest truth are off until the Space profile or Space settings opt in. Enabling live PRO on the game server also requires worker URLs and the same `NUTONIC_INFERENCE_HMAC_SECRET` used by any HMAC-protected worker.

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "httpx>=0.27.0",
     "PyJWT>=2.9.0",
     "sqlalchemy>=2.0.36",
+    "huggingface_hub>=0.35.0",
 ]
 
 [project.optional-dependencies]

src/nutonic_server/deps.py

@@ -7,9 +7,11 @@ from fastapi import Depends, HTTPException, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from nutonic_server.jwt_tokens import decode_bearer_token
+from nutonic_server.hf_persistence import HfSqliteSync
 from nutonic_server.pro_jobs_runner import ProJobRunner
 from nutonic_server.pro_jobs_store import ProJobStore, create_pro_job_store
 from nutonic_server.settings import Settings, load_settings
+from nutonic_server.leaderboard_store import sqlite_file_path_from_url
 
 _bearer = HTTPBearer(auto_error=False)
 _pro_job_stores: dict[str, ProJobStore] = {}
@@ -31,7 +33,14 @@ def get_pro_job_store_for_settings(settings: Settings) -> ProJobStore:
         raise HTTPException(status_code=500, detail="Unsupported PRO job backend")
     url = settings.pro_job_database_url.strip()
     if url not in _pro_job_stores:
-        _pro_job_stores[url] = create_pro_job_store(url)
+        sync_hook = None
+        db_path = sqlite_file_path_from_url(url)
+        if db_path is not None:
+            hf = HfSqliteSync.from_settings(settings)
+            if hf is not None:
+                hf.bootstrap_sqlite_file(local_path=db_path, logical_name="pro_jobs")
+                sync_hook = hf.make_write_sync_hook(local_path=db_path, logical_name="pro_jobs")
+        _pro_job_stores[url] = create_pro_job_store(url, on_write=sync_hook)
     return _pro_job_stores[url]
 
 

src/nutonic_server/guess_telemetry_store.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from threading import Lock
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 
 from sqlalchemy import Column, Float, Integer, MetaData, String, Table, insert, select
 
@@ -49,9 +49,10 @@ class GuessTelemetryIn:
 
 
 class GuessTelemetryStore:
-    def __init__(self, engine: Engine) -> None:
+    def __init__(self, engine: Engine, *, on_write: Callable[[], None] | None = None) -> None:
         self._engine = engine
         self._lock = Lock()
+        self._on_write = on_write
 
     def initialize_schema(self) -> None:
         metadata.create_all(self._engine)
@@ -98,8 +99,14 @@ class GuessTelemetryStore:
                             row_id=rid,
                         )
                     )
+                self._sync_after_write()
                 return int(rid)
 
+    def _sync_after_write(self) -> None:
+        if self._on_write is None:
+            return
+        self._on_write()
+
 
 def create_guess_telemetry_engine(url: str):
     from nutonic_server.leaderboard_store import create_leaderboard_engine
@@ -108,13 +115,22 @@ def create_guess_telemetry_engine(url: str):
 
 
 def create_guess_telemetry_store(url: str) -> GuessTelemetryStore | None:
-    from nutonic_server.leaderboard_store import _ensure_parent_dir_for_sqlite_file
+    from nutonic_server.hf_persistence import HfSqliteSync
+    from nutonic_server.leaderboard_store import _ensure_parent_dir_for_sqlite_file, sqlite_file_path_from_url
+    from nutonic_server.settings import load_settings
 
     u = url.strip()
     if not u or u.lower() == "disabled":
         return None
     _ensure_parent_dir_for_sqlite_file(u)
+    sync_hook = None
+    db_path = sqlite_file_path_from_url(u)
+    if db_path is not None:
+        hf = HfSqliteSync.from_settings(load_settings())
+        if hf is not None:
+            hf.bootstrap_sqlite_file(local_path=db_path, logical_name="guess_telemetry")
+            sync_hook = hf.make_write_sync_hook(local_path=db_path, logical_name="guess_telemetry")
     eng = create_guess_telemetry_engine(u)
-    st = GuessTelemetryStore(eng)
+    st = GuessTelemetryStore(eng, on_write=sync_hook)
     st.initialize_schema()
     return st

src/nutonic_server/hf_persistence.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Lock
+
+
+@dataclass(frozen=True)
+class HfSqliteSyncConfig:
+    enabled: bool
+    repo_id: str
+    dataset_subdir: str
+    startup_pull_mode: str = "if_missing"
+    required: bool = False
+    token: str | None = None
+
+
+class HfSqliteSync:
+    """Sync local SQLite files to a Hugging Face Dataset repo."""
+
+    def __init__(self, config: HfSqliteSyncConfig) -> None:
+        self._config = config
+        self._lock = Lock()
+        self._api = None
+
+    @classmethod
+    def from_settings(cls, settings) -> HfSqliteSync | None:
+        enabled = bool(getattr(settings, "hf_persistence_enabled", False))
+        required = bool(getattr(settings, "hf_persistence_required", False))
+        # Lazy-check optional dependency and env wiring only when explicitly enabled.
+        if not enabled:
+            return None
+        repo_id = str(getattr(settings, "hf_persistence_repo_id", "") or "").strip()
+        if not repo_id:
+            if required:
+                raise RuntimeError(
+                    "HF persistence is required but NUTONIC_HF_PERSISTENCE_REPO_ID/HF_PERSISTENCE_REPO_ID is missing."
+                )
+            return None
+        token = (
+            os.environ.get("NUTONIC_HF_PERSISTENCE_TOKEN")
+            or os.environ.get("HF_API_WRITE")
+            or os.environ.get("HF_TOKEN")
+            or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+            or None
+        )
+        if required and not token:
+            raise RuntimeError(
+                "HF persistence is required but no HF write token is set "
+                "(NUTONIC_HF_PERSISTENCE_TOKEN/HF_API_WRITE/HF_TOKEN/HUGGING_FACE_HUB_TOKEN)."
+            )
+        subdir = str(getattr(settings, "hf_persistence_dataset_subdir", "server-persistence") or "server-persistence").strip(
+            "/"
+        )
+        startup_pull_mode = str(getattr(settings, "hf_persistence_startup_pull_mode", "if_missing") or "if_missing").strip().lower()
+        if startup_pull_mode not in ("if_missing", "always"):
+            raise RuntimeError(
+                "Invalid HF persistence startup pull mode. "
+                "Use NUTONIC_HF_PERSISTENCE_STARTUP_PULL_MODE=if_missing|always."
+            )
+        return cls(
+            HfSqliteSyncConfig(
+                enabled=True,
+                repo_id=repo_id,
+                dataset_subdir=subdir,
+                startup_pull_mode=startup_pull_mode,
+                required=required,
+                token=token,
+            )
+        )
+
+    def bootstrap_sqlite_file(self, *, local_path: Path, logical_name: str) -> None:
+        """Pull remote DB file at startup based on configured pull mode."""
+        if self._config.startup_pull_mode == "if_missing" and local_path.exists():
+            return
+        try:
+            from huggingface_hub import hf_hub_download
+        except Exception:
+            if self._config.required:
+                raise RuntimeError("HF persistence required but huggingface_hub is unavailable.")
+            return
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        remote_path = self._remote_path(logical_name)
+        try:
+            hf_hub_download(
+                repo_id=self._config.repo_id,
+                repo_type="dataset",
+                filename=remote_path,
+                local_dir=str(local_path.parent),
+                local_dir_use_symlinks=False,
+                token=self._config.token,
+            )
+            downloaded = local_path.parent / remote_path
+            if downloaded.exists() and downloaded != local_path:
+                downloaded.replace(local_path)
+        except Exception:
+            if self._config.required:
+                raise
+            return
+
+    def make_write_sync_hook(self, *, local_path: Path, logical_name: str):
+        def _sync() -> None:
+            if not local_path.exists():
+                return
+            try:
+                self._upload_file(local_path=local_path, logical_name=logical_name)
+            except Exception:
+                if self._config.required:
+                    raise
+                return
+
+        return _sync
+
+    def _upload_file(self, *, local_path: Path, logical_name: str) -> None:
+        with self._lock:
+            api = self._get_api()
+            api.create_repo(
+                repo_id=self._config.repo_id,
+                repo_type="dataset",
+                private=True,
+                exist_ok=True,
+            )
+            api.upload_file(
+                path_or_fileobj=str(local_path),
+                path_in_repo=self._remote_path(logical_name),
+                repo_id=self._config.repo_id,
+                repo_type="dataset",
+            )
+
+    def _remote_path(self, logical_name: str) -> str:
+        safe = "".join(ch if ch.isalnum() or ch in ("-", "_", ".") else "_" for ch in logical_name).strip("._")
+        safe = safe or "database"
+        return f"{self._config.dataset_subdir}/{safe}.sqlite3"
+
+    def _get_api(self):
+        if self._api is not None:
+            return self._api
+        from huggingface_hub import HfApi
+
+        self._api = HfApi(token=self._config.token)
+        return self._api

src/nutonic_server/leaderboard_store.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path
 from threading import Lock
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Callable, Protocol, runtime_checkable
 
 from sqlalchemy import (
     Column,
@@ -163,9 +163,10 @@ def _row_from_db(
 class SqliteLeaderboardStore:
     """IMP-060: durable community leaderboard rows + POST idempotency."""
 
-    def __init__(self, engine: Engine) -> None:
+    def __init__(self, engine: Engine, *, on_write: Callable[[], None] | None = None) -> None:
         self._engine = engine
         self._lock = Lock()
+        self._on_write = on_write
 
     def initialize_schema(self) -> None:
         metadata.create_all(self._engine)
@@ -192,6 +193,7 @@ class SqliteLeaderboardStore:
                             distance_km=r.distance_km,
                         )
                     )
+            self._sync_after_write()
 
     def list_rows(self, map_id: str) -> list[LeaderboardRow]:
         with self._lock:
@@ -262,8 +264,14 @@ class SqliteLeaderboardStore:
                             row_id=row_id,
                         )
                     )
+        self._sync_after_write()
         return row
 
+    def _sync_after_write(self) -> None:
+        if self._on_write is None:
+            return
+        self._on_write()
+
 
 def create_leaderboard_store(settings: Settings) -> LeaderboardStore:
     """Factory: SQLite by default; `memory` (case-insensitive) keeps in-process S0 store."""
@@ -271,7 +279,26 @@ def create_leaderboard_store(settings: Settings) -> LeaderboardStore:
     if url.lower() == "memory":
         return InMemoryLeaderboardStore()
     _ensure_parent_dir_for_sqlite_file(url)
+    sync_hook = None
+    db_path = sqlite_file_path_from_url(url)
+    if db_path is not None:
+        from nutonic_server.hf_persistence import HfSqliteSync
+
+        hf = HfSqliteSync.from_settings(settings)
+        if hf is not None:
+            hf.bootstrap_sqlite_file(local_path=db_path, logical_name="leaderboard")
+            sync_hook = hf.make_write_sync_hook(local_path=db_path, logical_name="leaderboard")
     engine = create_leaderboard_engine(url)
-    store = SqliteLeaderboardStore(engine)
+    store = SqliteLeaderboardStore(engine, on_write=sync_hook)
     store.initialize_schema()
     return store
+
+
+def sqlite_file_path_from_url(url: str) -> Path | None:
+    u = make_url(url)
+    if u.drivername not in ("sqlite", "sqlite+pysqlite"):
+        return None
+    db = u.database
+    if not db or db == ":memory:":
+        return None
+    return Path(db)

src/nutonic_server/pro_jobs_store.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from threading import Lock
-from typing import Any, Literal, Protocol
+from typing import Any, Callable, Literal, Protocol
 
 from sqlalchemy import Boolean, Column, Integer, MetaData, String, Table, create_engine, delete, event, insert, select, text, update
 from sqlalchemy.engine import Engine, make_url
@@ -107,9 +107,10 @@ class ProJobStore(Protocol):
 
 
 class SqliteProJobStore:
-    def __init__(self, engine: Engine) -> None:
+    def __init__(self, engine: Engine, *, on_write: Callable[[], None] | None = None) -> None:
         self._engine = engine
         self._lock = Lock()
+        self._on_write = on_write
 
     def initialize_schema(self) -> None:
         metadata.create_all(self._engine)
@@ -139,6 +140,7 @@ class SqliteProJobStore:
                 for name, ddl in required_columns.items():
                     if name not in existing:
                         conn.execute(text(f"ALTER TABLE pro_jobs ADD COLUMN {name} {ddl}"))
+                        self._sync_after_write()
 
     def create_job(self, *, session_id: str, analysis_profile: str, request_params: dict[str, Any]) -> ProJobRecord:
         now = _utc_now()
@@ -163,6 +165,7 @@ class SqliteProJobStore:
                         progress_pct=record.progress_pct,
                     )
                 )
+        self._sync_after_write()
         return record
 
     def get_job(self, job_id: str, *, session_id: str | None = None) -> ProJobRecord | None:
@@ -227,6 +230,7 @@ class SqliteProJobStore:
                 )
                 if not res.rowcount:
                     return None
+        self._sync_after_write()
         return self.get_job(job_id)
 
     def update_progress(self, job_id: str, *, progress_pct: int) -> None:
@@ -237,6 +241,7 @@ class SqliteProJobStore:
                     .where(pro_jobs.c.job_id == job_id)
                     .values(progress_pct=max(0, min(int(progress_pct), 100)))
                 )
+        self._sync_after_write()
 
     def complete(
         self,
@@ -266,6 +271,7 @@ class SqliteProJobStore:
                 )
                 if not res.rowcount:
                     return None
+        self._sync_after_write()
         return self.get_job(job_id)
 
     def fail(self, job_id: str, *, error_class: str, error_detail: str | None = None) -> ProJobRecord | None:
@@ -283,6 +289,7 @@ class SqliteProJobStore:
                 )
                 if not res.rowcount:
                     return None
+        self._sync_after_write()
         return self.get_job(job_id)
 
     def request_cancel(self, job_id: str, *, session_id: str) -> str:
@@ -303,6 +310,7 @@ class SqliteProJobStore:
                         .where(pro_jobs.c.job_id == job_id)
                         .values(status="cancelled", finished_at=_utc_now(), progress_pct=0, error_class="cancelled")
                     )
+                    self._sync_after_write()
                     return "cancelled"
                 if current == "running":
                     conn.execute(
@@ -310,6 +318,7 @@ class SqliteProJobStore:
                         .where(pro_jobs.c.job_id == job_id)
                         .values(cancel_requested=True)
                     )
+                    self._sync_after_write()
                     return "cancelling"
                 return current
 
@@ -330,12 +339,19 @@ class SqliteProJobStore:
                         pro_jobs.c.finished_at < cutoff_s,
                     )
                 )
+        if rows:
+            self._sync_after_write()
         if artifact_root:
             root = Path(artifact_root)
             for (job_id,) in rows:
                 _delete_job_artifacts(root / str(job_id))
         return len(rows)
 
+    def _sync_after_write(self) -> None:
+        if self._on_write is None:
+            return
+        self._on_write()
+
 
 def create_pro_job_engine(url: str) -> Engine:
     u = make_url(url)
@@ -360,9 +376,9 @@ def create_pro_job_engine(url: str) -> Engine:
     return engine
 
 
-def create_pro_job_store(url: str) -> SqliteProJobStore:
+def create_pro_job_store(url: str, *, on_write: Callable[[], None] | None = None) -> SqliteProJobStore:
     _ensure_parent_dir_for_sqlite_file(url)
-    store = SqliteProJobStore(create_pro_job_engine(url))
+    store = SqliteProJobStore(create_pro_job_engine(url), on_write=on_write)
     store.initialize_schema()
     return store
 

src/nutonic_server/ranked_store.py

@@ -6,7 +6,7 @@ import uuid
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from threading import Lock
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Callable, Literal
 
 from sqlalchemy import Column, Float, Integer, MetaData, String, Table, create_engine, delete, desc, insert, select, text, update
 from sqlalchemy.dialects.sqlite import insert as sqlite_insert
@@ -74,9 +74,10 @@ class RankedVerifiedLbRow:
 
 
 class SqliteRankedStore:
-    def __init__(self, engine: Engine) -> None:
+    def __init__(self, engine: Engine, *, on_write: Callable[[], None] | None = None) -> None:
         self._engine = engine
         self._lock = Lock()
+        self._on_write = on_write
 
     def initialize_schema(self) -> None:
         metadata.create_all(self._engine)
@@ -90,6 +91,7 @@ class SqliteRankedStore:
                 names = {str(r[1]) for r in rows}
                 if "opened_at_epoch" not in names:
                     conn.execute(text("ALTER TABLE ranked_rounds ADD COLUMN opened_at_epoch INTEGER NOT NULL DEFAULT 0"))
+                    self._sync_after_write()
 
     def prune_stale_open_rounds(self, *, now_epoch: int, max_age_seconds: int) -> int:
         """Delete ``open`` rounds whose ``opened_at_epoch`` is older than ``now_epoch - max_age_seconds``."""
@@ -104,6 +106,8 @@ class SqliteRankedStore:
                         ranked_rounds.c.opened_at_epoch < cutoff,
                     )
                 )
+                if (res.rowcount or 0) > 0:
+                    self._sync_after_write()
                 return int(res.rowcount or 0)
 
     def create_round(
@@ -131,6 +135,7 @@ class SqliteRankedStore:
                         opened_at_epoch=opened,
                     )
                 )
+        self._sync_after_write()
         return rid
 
     def get_round(self, round_id: str) -> RankedRoundRow | None:
@@ -160,6 +165,7 @@ class SqliteRankedStore:
                     .where(ranked_rounds.c.round_id == round_id)
                     .values(status="submitted")
                 )
+        self._sync_after_write()
 
     def forfeit_round(self, round_id: str, session_id: str) -> RankedForfeitResult:
         """Mark ``open`` round as ``forfeited`` when ``session_id`` matches (IMP-091)."""
@@ -183,6 +189,7 @@ class SqliteRankedStore:
                     .where(ranked_rounds.c.round_id == round_id)
                     .values(status="forfeited")
                 )
+        self._sync_after_write()
         return "ok"
 
     def get_submit_if_exists(self, round_id: str, idempotency_key: str) -> tuple[float, int] | None:
@@ -225,6 +232,7 @@ class SqliteRankedStore:
                         score_points=score_points,
                     )
                 )
+                self._sync_after_write()
                 return distance_km, score_points, True
 
     def append_verified_leaderboard(
@@ -247,6 +255,7 @@ class SqliteRankedStore:
                     distance_km=distance_km,
                 )
                 conn.execute(stmt.on_conflict_do_nothing(index_elements=["round_id"]))
+        self._sync_after_write()
 
     def list_ranked_leaderboard(self, map_id: str) -> list[RankedVerifiedLbRow]:
         """Verified ranked rows for ``map_id``, highest score first."""
@@ -275,6 +284,11 @@ class SqliteRankedStore:
             )
         return out
 
+    def _sync_after_write(self) -> None:
+        if self._on_write is None:
+            return
+        self._on_write()
+
 
 def create_ranked_engine(url: str) -> Engine:
     from nutonic_server.leaderboard_store import create_leaderboard_engine
@@ -283,10 +297,19 @@ def create_ranked_engine(url: str) -> Engine:
 
 
 def create_ranked_store(url: str) -> SqliteRankedStore:
-    from nutonic_server.leaderboard_store import _ensure_parent_dir_for_sqlite_file
+    from nutonic_server.leaderboard_store import _ensure_parent_dir_for_sqlite_file, sqlite_file_path_from_url
+    from nutonic_server.hf_persistence import HfSqliteSync
+    from nutonic_server.settings import load_settings
 
     _ensure_parent_dir_for_sqlite_file(url)
+    sync_hook = None
+    db_path = sqlite_file_path_from_url(url)
+    if db_path is not None:
+        hf = HfSqliteSync.from_settings(load_settings())
+        if hf is not None:
+            hf.bootstrap_sqlite_file(local_path=db_path, logical_name="ranked")
+            sync_hook = hf.make_write_sync_hook(local_path=db_path, logical_name="ranked")
     eng = create_ranked_engine(url)
-    st = SqliteRankedStore(eng)
+    st = SqliteRankedStore(eng, on_write=sync_hook)
     st.initialize_schema()
     return st

src/nutonic_server/settings.py

@@ -265,6 +265,42 @@ class Settings(BaseSettings):
         ),
     )
 
+    hf_persistence_enabled: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("NUTONIC_HF_PERSISTENCE_ENABLED", "HF_PERSISTENCE_ENABLED"),
+        description="When true, mirror SQLite server DB files to a Hugging Face Dataset repo.",
+    )
+
+    hf_persistence_required: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("NUTONIC_HF_PERSISTENCE_REQUIRED", "HF_PERSISTENCE_REQUIRED"),
+        description=(
+            "When true with HF persistence enabled, fail fast if the dataset repo/token is missing "
+            "or sync operations fail."
+        ),
+    )
+
+    hf_persistence_repo_id: str = Field(
+        default="",
+        validation_alias=AliasChoices("NUTONIC_HF_PERSISTENCE_REPO_ID", "HF_PERSISTENCE_REPO_ID"),
+        description="Dataset repo id (owner/name) used for SQLite persistence mirroring.",
+    )
+
+    hf_persistence_dataset_subdir: str = Field(
+        default="server-persistence",
+        validation_alias=AliasChoices("NUTONIC_HF_PERSISTENCE_SUBDIR", "HF_PERSISTENCE_SUBDIR"),
+        description="Subdirectory inside the Dataset repo where DB files are stored.",
+    )
+
+    hf_persistence_startup_pull_mode: str = Field(
+        default="if_missing",
+        validation_alias=AliasChoices(
+            "NUTONIC_HF_PERSISTENCE_STARTUP_PULL_MODE",
+            "HF_PERSISTENCE_STARTUP_PULL_MODE",
+        ),
+        description="Startup pull policy for local SQLite files: if_missing (default) or always.",
+    )
+
     @field_validator("cors_origins", mode="before")
     @classmethod
     def strip_origins(cls, v: object) -> str: