steam-data-reader 1.0.0.dev1__py3-none-any.whl

steam_data_reader/database.py

@@ -0,0 +1,271 @@
+"""Installed-code SQL only. Downloaded files supply data, never SQL or executable databases."""
+
+import hashlib
+import json
+from pathlib import Path
+
+import duckdb
+from steam_data_schema import (
+    APP_COLUMNS,
+    DESCRIPTIONS,
+    INFO_COLUMNS,
+    JSON_FIELDS,
+    TABLES,
+    TEXT_FIELDS,
+    canonical,
+)
+
+
+def connect(path, *, read_only=False, memory_limit="768MB"):
+    connection = duckdb.connect(
+        str(path),
+        read_only=read_only,
+        config={
+            "autoinstall_known_extensions": "false",
+            "autoload_known_extensions": "false",
+            "threads": "2",
+            "memory_limit": memory_limit,
+        },
+    )
+    connection.execute("SET TimeZone='UTC'")
+    return connection
+
+
+def initialize(c):
+    c.execute("CREATE SCHEMA transport; CREATE SCHEMA steam")
+    for name, spec in TABLES.items():
+        cols = ",".join(
+            f'"{n}" {t}' + (" NOT NULL" if n in spec["key"] else "")
+            for n, t in spec["columns"].items()
+        )
+        # ART primary-key indexes cannot spill and exceed modest memory budgets
+        # for millions of provenance rows. apply_tables validates incoming keys;
+        # validate_state also checks the complete state using spillable SQL.
+        c.execute(f"CREATE TABLE transport.{name} ({cols})")
+    c.execute(
+        "CREATE TABLE steam.snapshot_info ("
+        + ",".join(f"{n} {t}" for n, t in INFO_COLUMNS.items())
+        + ")"
+    )
+    for name in TABLES:
+        if not name.startswith("app_") or name in (
+            "app_organizations",
+            "app_relationships",
+            "app_genres",
+            "app_categories",
+            "app_tags",
+        ):
+            c.execute(f"CREATE VIEW steam.{name} AS SELECT * FROM transport.{name}")
+    selections = {
+        "steam_appid": "c.steam_appid",
+        "name": "coalesce(d.name,c.catalog_name)",
+        "steam_url": "'https://store.steampowered.com/app/' || c.steam_appid",
+        "name_origin": "CASE WHEN d.name IS NOT NULL THEN 'details' WHEN c.catalog_name IS NOT NULL THEN 'catalog' ELSE 'unknown' END",
+        "first_seen_at": "c.first_seen_at",
+        "last_seen_at": "c.last_seen_at",
+        "is_free": "d.is_free",
+        "default_review_series_id": "i.default_review_series_id",
+        "reviews_observed_at": "r.observed_at",
+        "price_country": "p.country",
+        "price_currency": "p.currency",
+        "price_initial_minor": "p.initial_minor",
+        "price_final_minor": "p.final_minor",
+        "price_discount_percentage": "p.discount_percentage",
+        "price_observed_at": "p.observed_at",
+    }
+    selections.update({f: "d." + f for f in TEXT_FIELDS + JSON_FIELDS if f != "name"})
+    selections.update({f: "x." + f for f in DESCRIPTIONS})
+    selections.update(
+        {f: "s." + f for f in ("developers", "publishers", "genres", "categories", "tags")}
+    )
+    selections.update(
+        {
+            f: "r." + f
+            for f in (
+                "total_positive",
+                "total_negative",
+                "total_reviews",
+                "positive_percentage",
+                "review_score",
+                "review_score_desc",
+            )
+        }
+    )
+    c.execute(
+        "CREATE VIEW steam.apps AS SELECT "
+        + ",".join(f'{selections[f]} AS "{f}"' for f in APP_COLUMNS)
+        + """
+        FROM transport.app_catalog c CROSS JOIN steam.snapshot_info i
+        LEFT JOIN transport.app_details d USING(steam_appid)
+        LEFT JOIN transport.app_descriptions x USING(steam_appid)
+        LEFT JOIN transport.app_sets s USING(steam_appid)
+        LEFT JOIN transport.review_summaries r ON r.steam_appid=c.steam_appid AND r.review_series_id=i.default_review_series_id
+        LEFT JOIN transport.prices p ON p.steam_appid=c.steam_appid AND p.country=i.price_country AND p.language=i.price_language
+    """
+    )
+
+
+def set_info(c, m):
+    info = {f: m.get(f) for f in INFO_COLUMNS}
+    info.update(
+        dataset_version=m["dataset_version"],
+        coverage_json=canonical(m["coverage"]).decode(),
+        feature_support_json=canonical(m["feature_support"]).decode(),
+        freshness_json=canonical(m.get("freshness", {})).decode(),
+    )
+    c.execute("DELETE FROM steam.snapshot_info")
+    c.execute(
+        "INSERT INTO steam.snapshot_info VALUES (" + ",".join("?" for _ in info) + ")",
+        list(info.values()),
+    )
+
+
+def decoded(row, columns):
+    return {
+        name: json.loads(value) if kind == "JSON" and value is not None else value
+        for (name, kind), value in zip(columns.items(), row)
+    }
+
+
+def app_ranges(c, size=4096):
+    """Inclusive upper bounds covering all numeric appIDs, including removed apps."""
+    bounds = c.execute(
+        "SELECT max(steam_appid) FROM (SELECT steam_appid,(row_number() OVER(ORDER BY steam_appid)-1)//? AS batch FROM transport.app_catalog) GROUP BY batch ORDER BY batch",
+        [size],
+    ).fetchall()
+    lower = None
+    for (upper,) in bounds[:-1]:
+        yield lower, upper
+        lower = upper
+    yield lower, None
+
+
+def range_filter(bounds, alias=""):
+    lower, upper = bounds
+    col = alias + "steam_appid"
+    return (
+        " AND ".join(
+            ([f"{col}>{int(lower)}"] if lower is not None else [])
+            + ([f"{col}<={int(upper)}"] if upper is not None else [])
+        )
+        or "true"
+    )
+
+
+def logical_hash(c, *, app_batch_size=None):
+    digest = hashlib.sha256()
+    ranges = list(app_ranges(c, app_batch_size)) if app_batch_size else [(None, None)]
+    for name, spec in sorted(TABLES.items()):
+        # DuckDB cursor() creates an independent connection, outside this transaction.
+        cur = c
+        for bounds in ranges if "steam_appid" in spec["columns"] else [(None, None)]:
+            where = range_filter(bounds) if "steam_appid" in spec["columns"] else "true"
+            cur.execute(
+                f"SELECT * FROM transport.{name} WHERE {where} ORDER BY " + ",".join(spec["key"])
+            )
+            while batch := cur.fetchmany(1000):
+                for row in batch:
+                    digest.update(canonical([name, decoded(row, spec["columns"])]))
+                    digest.update(b"\n")
+    return digest.hexdigest()
+
+
+def apply_tables(c, root, m):
+    for name, spec in TABLES.items():
+        columns = spec["columns"]
+        c.execute(
+            f"CREATE TEMP TABLE incoming_{name} AS SELECT *, ''::VARCHAR AS _op FROM transport.{name} WHERE false"
+        )
+        for f in m["tables"][name]["files"]:
+            path = str(Path(root) / f["path"])
+            selected = (
+                columns if f["operation"] == "upsert" else {k: columns[k] for k in spec["key"]}
+            )
+            description = c.execute("DESCRIBE SELECT * FROM read_parquet(?)", [path]).fetchall()
+            actual = {
+                r[0]: "TIMESTAMPTZ"
+                if r[1] == "TIMESTAMP WITH TIME ZONE"
+                else "VARCHAR"
+                if r[1] == "JSON"
+                else r[1]
+                for r in description
+            }
+            expected = {k: "VARCHAR" if v == "JSON" else v for k, v in selected.items()}
+            if actual != expected:
+                raise ValueError(f"Parquet schema mismatch for {name}")
+            count = c.execute("SELECT count(*) FROM read_parquet(?)", [path]).fetchone()[0]
+            if count != f["rows"]:
+                raise ValueError("Parquet row count mismatch")
+            target = ",".join(selected)
+            c.execute(
+                f"INSERT INTO incoming_{name} ({target},_op) SELECT {target}, ? FROM read_parquet(?)",
+                [f["operation"], path],
+            )
+        keys = ",".join(spec["key"])
+        nulls = " OR ".join(k + " IS NULL" for k in spec["key"])
+        if c.execute(f"SELECT count(*) FROM incoming_{name} WHERE {nulls}").fetchone()[0]:
+            raise ValueError("Null logical key")
+        if c.execute(
+            f"SELECT 1 FROM incoming_{name} GROUP BY {keys} HAVING count(*)>1 LIMIT 1"
+        ).fetchone():
+            raise ValueError("Duplicate operation for logical key")
+        match = " AND ".join(f"a.{k}=b.{k}" for k in spec["key"])
+        c.execute(f"DELETE FROM transport.{name} a USING incoming_{name} b WHERE {match}")
+        c.execute(
+            f"INSERT INTO transport.{name} SELECT "
+            + ",".join(columns)
+            + f" FROM incoming_{name} WHERE _op='upsert'"
+        )
+        c.execute(f"DROP TABLE incoming_{name}")
+
+
+def validate_state(c, m, *, verify_hash=True, app_batch_size=None):
+    count = c.execute("SELECT count(*) FROM transport.app_catalog").fetchone()[0]
+    if count != m["app_count"]:
+        raise ValueError("Catalog count mismatch")
+    ranges = list(app_ranges(c, app_batch_size)) if app_batch_size else [(None, None)]
+    for name, spec in TABLES.items():
+        keys = ",".join(spec["key"])
+        for bounds in ranges if "steam_appid" in spec["columns"] else [(None, None)]:
+            where = range_filter(bounds) if "steam_appid" in spec["columns"] else "true"
+            if c.execute(
+                f"SELECT 1 FROM transport.{name} WHERE {where} GROUP BY {keys} HAVING count(*)>1 LIMIT 1"
+            ).fetchone():
+                raise ValueError("Duplicate current logical key")
+        if (
+            c.execute(f"SELECT count(*) FROM transport.{name}").fetchone()[0]
+            != m["tables"][name]["rows"]
+        ):
+            raise ValueError("Current table row-count mismatch")
+        if (
+            "steam_appid" in spec["columns"]
+            and name != "app_catalog"
+            and c.execute(
+                f"SELECT 1 FROM transport.{name} a ANTI JOIN transport.app_catalog c USING(steam_appid) LIMIT 1"
+            ).fetchone()
+        ):
+            raise ValueError("Orphan app reference")
+    for plural, singular in (("genres", "genre"), ("categories", "category"), ("tags", "tag")):
+        key = singular + "_id"
+        if c.execute(
+            f"SELECT 1 FROM transport.app_{plural} ANTI JOIN transport.{plural} USING({key}) LIMIT 1"
+        ).fetchone():
+            raise ValueError("Orphan classification reference")
+    if c.execute(
+        "SELECT 1 FROM transport.review_summaries WHERE total_positive<0 OR total_negative<0 OR total_reviews<0 OR total_positive+total_negative!=total_reviews OR total_reviews IS NULL OR total_positive IS NULL OR total_negative IS NULL OR (total_reviews=0 AND positive_percentage IS NOT NULL) OR (total_reviews>0 AND (positive_percentage IS NULL OR abs(positive_percentage-100.0*total_positive/total_reviews)>1e-9)) LIMIT 1"
+    ).fetchone():
+        raise ValueError("Invalid review metrics")
+    if c.execute(
+        "SELECT 1 FROM transport.review_summaries ANTI JOIN transport.review_series USING(review_series_id) LIMIT 1"
+    ).fetchone():
+        raise ValueError("Unknown review series")
+    if c.execute(
+        "SELECT 1 FROM transport.prices GROUP BY steam_appid,country,language HAVING count(*)>1 LIMIT 1"
+    ).fetchone():
+        raise ValueError("Ambiguous current price context")
+    if c.execute(
+        "SELECT 1 FROM transport.prices WHERE currency IS NULL OR currency='' OR initial_minor<0 OR final_minor<0 OR discount_percentage NOT BETWEEN 0 AND 100 LIMIT 1"
+    ).fetchone():
+        raise ValueError("Invalid current price")
+    if verify_hash and logical_hash(c, app_batch_size=app_batch_size) != m["logical_state_sha256"]:
+        raise ValueError("Logical state checksum mismatch")

steam_data_reader/sync.py

@@ -0,0 +1,333 @@
+"""Verified HTTPS acquisition and atomic data-only snapshot installation."""
+
+import hashlib
+import ipaddress
+import json
+import os
+import shutil
+import stat
+import tempfile
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from steam_data_schema import (
+    DATASET_ID,
+    READER_VERSION,
+    canonical,
+    check_compatibility,
+    sha256,
+    validate_manifest,
+)
+
+from .catalog import dataset_lock, staged_text
+from .database import apply_tables, connect, initialize, set_info, validate_state
+
+MAX_JSON = 4 * 1024**2
+MAX_BUNDLE = 8 * 1024**3
+MAX_EXPANDED = 20 * 1024**3
+DEFAULT_SOURCE_URL = "https://pub-93fc6f5a294444c1adec0db48e691e3a.r2.dev/latest.json"
+
+
+class SyncError(RuntimeError):
+    def __init__(self, message, *, installed_version=None, target_version=None, progress=None):
+        super().__init__(message)
+        self.installed_version, self.target_version, self.progress = (
+            installed_version,
+            target_version,
+            progress,
+        )
+
+
+class ReaderUpgradeRequired(SyncError):
+    pass
+
+
+@dataclass
+class SyncResult:
+    previous_version: str | None
+    installed_version: str | None
+    target_version: str | None
+    bytes_downloaded: int = 0
+    applied_increments: int = 0
+    baseline_replaced: bool = False
+    complete: bool = False
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def checked_url(url, allow_local_http=False):
+    parsed = urllib.parse.urlsplit(url)
+    local = False
+    try:
+        local = ipaddress.ip_address(parsed.hostname or "").is_loopback
+    except ValueError:
+        local = parsed.hostname == "localhost"
+    if (
+        (parsed.scheme != "https" and not (allow_local_http and parsed.scheme == "http" and local))
+        or parsed.username
+        or parsed.password
+        or not parsed.hostname
+    ):
+        raise ValueError(
+            "Download URLs must use HTTPS (explicit loopback HTTP is for private testing only)"
+        )
+    return url
+
+
+class Redirect(urllib.request.HTTPRedirectHandler):
+    def __init__(self, allow_local_http):
+        self.allow_local_http = allow_local_http
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        checked_url(newurl, self.allow_local_http)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+class Downloads:
+    def __init__(self, allow_local_http=False):
+        self.allow_local_http = allow_local_http
+        self.opener = urllib.request.build_opener(Redirect(allow_local_http))
+        self.bytes = 0
+
+    def fetch(self, url, path, *, limit, checksum=None, length=None):
+        checked_url(url, self.allow_local_http)
+        digest, size = hashlib.sha256(), 0
+        req = urllib.request.Request(
+            url,
+            headers={
+                "User-Agent": "steam-data-reader/" + READER_VERSION,
+                "Accept-Encoding": "identity",
+            },
+        )
+        with self.opener.open(req, timeout=60) as response, Path(path).open("wb") as output:
+            checked_url(response.url, self.allow_local_http)
+            while block := response.read(1024**2):
+                size += len(block)
+                self.bytes += len(block)
+                if size > limit:
+                    raise ValueError("Download exceeds configured bound")
+                digest.update(block)
+                output.write(block)
+        if (length is not None and size != length) or (checksum and digest.hexdigest() != checksum):
+            raise ValueError("Download length/checksum mismatch")
+
+    def json(self, url, path, *, checksum=None):
+        self.fetch(url, path, limit=MAX_JSON, checksum=checksum)
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def unpack(bundle, destination, manifest):
+    files = {f["path"]: f for t in manifest["tables"].values() for f in t["files"]}
+    expected = set(files) | {"data-manifest.json"}
+    with zipfile.ZipFile(bundle) as archive:
+        names = archive.namelist()
+        if len(names) != len(set(names)) or set(names) != expected or len(names) > 10000:
+            raise ValueError("Unexpected or duplicate archive entries")
+        total = sum(i.file_size for i in archive.infolist())
+        if total > MAX_EXPANDED or total != manifest["artifact"]["expanded_bytes"]:
+            raise ValueError("Expanded archive size mismatch")
+        for item in archive.infolist():
+            mode = item.external_attr >> 16
+            if (
+                item.flag_bits & 1
+                or stat.S_ISLNK(mode)
+                or (stat.S_IFMT(mode) not in (0, stat.S_IFREG))
+            ):
+                raise ValueError("Encrypted/link/special archive entry")
+            if item.filename == "data-manifest.json":
+                if item.file_size > MAX_JSON:
+                    raise ValueError("Oversized internal manifest")
+                body = archive.read(item)
+                if sha256(body) != manifest["artifact"]["data_manifest_sha256"] or json.loads(
+                    body
+                ) != {k: v for k, v in manifest.items() if k != "artifact"}:
+                    raise ValueError("Internal/external manifest mismatch")
+                continue
+            spec = files[item.filename]
+            if item.file_size != spec["bytes"]:
+                raise ValueError("Expanded file size mismatch")
+            path = Path(destination) / item.filename
+            path.parent.mkdir(parents=True, exist_ok=True)
+            digest = hashlib.sha256()
+            with archive.open(item) as source, path.open("wb") as output:
+                while block := source.read(1024**2):
+                    digest.update(block)
+                    output.write(block)
+            if digest.hexdigest() != spec["sha256"]:
+                raise ValueError("Parquet checksum mismatch")
+
+
+def install_release(path, extracted, manifest, *, baseline):
+    with connect(path, memory_limit="2048MB") as c:
+        c.execute("SET threads=1; SET preserve_insertion_order=false")
+        if baseline:
+            initialize(c)
+        c.execute("BEGIN")
+        try:
+            apply_tables(c, extracted, manifest)
+            set_info(c, manifest)
+            validate_state(c, manifest)
+            c.execute("COMMIT")
+            c.execute("CHECKPOINT")
+        except Exception:
+            c.execute("ROLLBACK")
+            raise
+
+
+def sync(directory, *, source_url=None, allow_local_http=False):
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    result = SyncResult(None, None, None)
+    downloads = None
+    try:
+        with dataset_lock(directory, exclusive=True):
+            installed = None
+            rebuild_transport = False
+            database = directory / "catalog.duckdb"
+            if database.exists():
+                # Also check DuckDB's writer lock before staging against readers outside our API.
+                with connect(database) as c:
+                    fields = [r[0] for r in c.execute("DESCRIBE steam.snapshot_info").fetchall()]
+                    installed = dict(
+                        zip(fields, c.execute("SELECT * FROM steam.snapshot_info").fetchone())
+                    )
+                    result.previous_version = result.installed_version = installed[
+                        "dataset_version"
+                    ]
+                    # Private preview caches used non-spillable ART indexes.
+                    # Rebuild through the verified replacement path so future
+                    # increments cannot keep growing those obsolete indexes.
+                    rebuild_transport = bool(
+                        c.execute(
+                            "SELECT 1 FROM duckdb_constraints() WHERE schema_name='transport' AND constraint_type='PRIMARY KEY' LIMIT 1"
+                        ).fetchone()
+                    )
+            settings = directory / "source.json"
+            source_url = source_url or (
+                json.loads(settings.read_text())["source_url"]
+                if settings.exists() else DEFAULT_SOURCE_URL
+            )
+            if not source_url:
+                raise ValueError("The configured snapshot source URL is empty")
+            checked_url(source_url, allow_local_http)
+            downloads = Downloads(allow_local_http)
+            with tempfile.TemporaryDirectory(dir=directory, prefix=".sync-") as temporary:
+                temporary = Path(temporary)
+                index = downloads.json(source_url, temporary / "index.json")
+                result.target_version = index["latest_version"]
+                for document in (index,):
+                    try:
+                        check_compatibility(document)
+                    except ValueError:
+                        raise ReaderUpgradeRequired(
+                            f"Reader {READER_VERSION} does not support schema {document.get('schema_version')}, protocol {document.get('protocol_version')} or required reader {document.get('minimum_reader_version')}. Upgrade with: python -m pip install --upgrade --pre steam-data-reader",
+                            installed_version=result.installed_version,
+                            target_version=result.target_version,
+                        ) from None
+                if index["dataset_id"] != DATASET_ID:
+                    raise ValueError("Unexpected dataset")
+                refs = [index["baseline"]] + index["increments"]
+                if len(refs) > 366:
+                    raise ValueError("Excessive increment chain")
+                manifests = []
+                for i, ref in enumerate(refs):
+                    url = urllib.parse.urljoin(source_url, ref["url"])
+                    m = downloads.json(
+                        url, temporary / f"manifest-{i}.json", checksum=ref["sha256"]
+                    )
+                    try:
+                        check_compatibility(m)
+                    except ValueError:
+                        raise ReaderUpgradeRequired(
+                            f"Reader upgrade required for schema {m.get('schema_version')}; run python -m pip install --upgrade steam-data-reader",
+                            installed_version=result.installed_version,
+                            target_version=result.target_version,
+                        ) from None
+                    validate_manifest(m)
+                    if any(
+                        m[k] != index[k]
+                        for k in ("dataset_id", "chain_id", "schema_version", "protocol_version")
+                    ):
+                        raise ValueError("Index/manifest identity mismatch")
+                    if i == 0 and m["kind"] != "baseline":
+                        raise ValueError("Chain does not start at baseline")
+                    if i and (
+                        m["kind"] != "increment"
+                        or m["parent_version"] != manifests[-1][0]["dataset_version"]
+                        or m["increment_sequence"] != i
+                        or m["baseline_version"] != manifests[0][0]["dataset_version"]
+                    ):
+                        raise ValueError("Broken increment chain")
+                    manifests.append((m, url))
+                if manifests[-1][0]["dataset_version"] != result.target_version:
+                    raise ValueError("Index does not reach advertised version")
+                versions = [m["dataset_version"] for m, _ in manifests]
+                same_chain = (
+                    installed
+                    and not rebuild_transport
+                    and installed["chain_id"] == index["chain_id"]
+                    and installed["schema_version"] == index["schema_version"]
+                    and installed["dataset_version"] in versions
+                )
+                start = versions.index(installed["dataset_version"]) + 1 if same_chain else 0
+                work = database if same_chain else temporary / "replacement.duckdb"
+                if same_chain:
+                    wanted = manifests[start - 1][0]["logical_state_sha256"]
+                    if installed["logical_state_sha256"] != wanted:
+                        raise ValueError("Installed version has different state identity")
+                for i in range(start, len(manifests)):
+                    m, url = manifests[i]
+                    artifact = m["artifact"]
+                    if (
+                        type(artifact["bytes"]) is not int
+                        or not 0 <= artifact["bytes"] <= MAX_BUNDLE
+                    ):
+                        raise ValueError("Bundle exceeds configured download limit")
+                    required = artifact["bytes"] + artifact["expanded_bytes"] * 3
+                    if shutil.disk_usage(directory).free < required:
+                        raise OSError("Insufficient free disk space for staged snapshot")
+                    bundle = temporary / "bundle.zip"
+                    downloads.fetch(
+                        urllib.parse.urljoin(url, artifact["url"]),
+                        bundle,
+                        limit=artifact["bytes"],
+                        checksum=artifact["sha256"],
+                        length=artifact["bytes"],
+                    )
+                    extracted = temporary / "extracted"
+                    extracted.mkdir(exist_ok=True)
+                    unpack(bundle, extracted, m)
+                    install_release(work, extracted, m, baseline=i == 0)
+                    shutil.rmtree(extracted)
+                    bundle.unlink()
+                    result.applied_increments += int(i > 0)
+                    if same_chain:
+                        result.installed_version = m["dataset_version"]
+                if not same_chain:
+                    # Windows' durable flush requires a writable file handle.
+                    with work.open("r+b") as stream:
+                        os.fsync(stream.fileno())
+                    os.replace(work, database)
+                    result.baseline_replaced = True
+                    result.installed_version = result.target_version
+                with staged_text(settings) as stream:
+                    stream.write(canonical({"source_url": source_url}).decode())
+                result.installed_version = result.target_version
+                result.bytes_downloaded = downloads.bytes
+                result.complete = True
+        return result
+    except ReaderUpgradeRequired:
+        raise
+    except Exception as error:  # noqa: BLE001 -- normalize download/database failures at public API boundary
+        if downloads is not None:
+            result.bytes_downloaded = downloads.bytes
+        raise SyncError(
+            f"Snapshot sync failed ({type(error).__name__}): {error}",
+            installed_version=result.installed_version,
+            target_version=result.target_version,
+            progress=result.to_dict(),
+        ) from None