sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/sync.py

@@ -0,0 +1,797 @@
+"""Closed-snapshot Sphynx archive and commit-gated ClickHouse projection.
+
+The sync process is separate from candidate execution. Its credentials never
+enter a candidate environment or an evidence bundle. Transport interfaces are
+small so the ordering and failure behavior can be verified without cloud access.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import os
+import re
+import stat
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import dataclass, field
+from importlib.resources import files as resource_files
+from pathlib import Path, PurePosixPath
+from typing import Any, Mapping, Protocol
+
+from .contracts import canonical_json
+from .evidence import RunRef, open_run, sha256_bytes, verify_run
+from .http_transport import open_no_redirect
+from .records import EVALUATION_SCHEMA_VERSION
+
+SNAPSHOT_SCHEMA = "sphynx.snapshot.v1"
+PROJECTION_SCHEMA = "sphynx.projection.v1"
+FACT_SCHEMA = "sphynx.fact.v1"
+COMMIT_SCHEMA = "sphynx.projection-commit.v1"
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_RUN_ID = re.compile(r"run-[0-9a-f]{32}\Z")
+_GENERATION = re.compile(r"[1-9][0-9]*\Z")
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_EVAL_ID = re.compile(r"^eval-[A-Za-z0-9]+$")
+_REPARSE = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+
+class SyncError(ValueError):
+    """A local snapshot or stored projection failed its integrity gate."""
+
+
+class SyncTransportError(RuntimeError):
+    """Remote storage failed; its original exception is intentionally hidden."""
+
+
+@dataclass(frozen=True)
+class StorageConfig:
+    """Explicit Sphynx destinations and identities; secrets are never rendered.
+
+    Keyless ADC/workload identity is the default. Optional service-account JSON
+    is read only by the lazy GCS adapter. Supply a separately scoped ClickHouse
+    identity with INSERT/SELECT on Sphynx tables.
+    The database and tables must be provisioned with the package migration.
+    """
+
+    gcs_bucket: str
+    gcs_prefix: str
+    gcs_identity: str
+    clickhouse_url: str
+    clickhouse_database: str
+    clickhouse_user: str
+    clickhouse_password: str = field(repr=False)
+    gcs_service_account_json: str | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if not re.fullmatch(r"[a-z0-9][a-z0-9._-]{2,221}", self.gcs_bucket or "") or "litmus" in self.gcs_bucket.lower():
+            raise ValueError("an explicit non-Litmus GCS bucket is required")
+        _safe_relative(self.gcs_prefix)
+        if "litmus" in self.gcs_prefix.lower():
+            raise ValueError("a non-Litmus GCS prefix is required")
+        if not self.gcs_identity or self.gcs_identity.lower() in {"default", "litmus"}:
+            raise ValueError("an explicit Sphynx GCS identity is required")
+        parsed = urllib.parse.urlsplit(self.clickhouse_url)
+        if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise ValueError("ClickHouse URL must be an HTTPS endpoint without credentials or query")
+        if not _IDENT.fullmatch(self.clickhouse_database or "") or self.clickhouse_database.lower() in {"default", "litmus"}:
+            raise ValueError("an explicit non-default Sphynx ClickHouse database is required")
+        if not _IDENT.fullmatch(self.clickhouse_user or "") or self.clickhouse_user.lower() in {"default", "litmus"}:
+            raise ValueError("an explicit non-default Sphynx ClickHouse user is required")
+        if not self.clickhouse_password:
+            raise ValueError("a separate ClickHouse credential is required")
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    status: str
+    projection_id: str | None
+    bundle_digest: str | None
+    archive_uri: str | None
+    archive_generation: str | None
+    stage: str | None = None
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class FactRow:
+    projection_id: str
+    row_id: str
+    row_hash: str
+    fact_type: str
+    run_id: str
+    case_id: str
+    capture_id: str
+    evaluation_id: str
+    metric_id: str
+    capability_id: str
+    status: str
+    numeric_value: float | None
+    payload_json: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return vars(self).copy()
+
+
+@dataclass(frozen=True)
+class CommitRow:
+    projection_id: str
+    commit_hash: str
+    payload_json: str
+
+    def to_dict(self) -> dict[str, str]:
+        return vars(self).copy()
+
+
+class ArchiveStore(Protocol):
+    def put_create_only(self, key: str, data: bytes) -> str: ...
+    def latest_generation(self, key: str) -> str | None: ...
+    def read_generation(self, key: str, generation: str) -> bytes: ...
+
+
+class FactStore(Protocol):
+    def insert_facts(self, rows: list[FactRow]) -> None: ...
+    def read_facts(self, projection_id: str) -> list[FactRow]: ...
+    def insert_commit(self, row: CommitRow) -> None: ...
+    def read_commits(self, projection_id: str) -> list[CommitRow]: ...
+
+
+def migration_sql(database: str) -> str:
+    """Return the package migration for an already-provisioned database."""
+
+    if not _IDENT.fullmatch(database) or database.lower() in {"default", "litmus"}:
+        raise ValueError("invalid Sphynx database name")
+    return resource_files("sphynx").joinpath("sql/001_sync_v1.sql").read_text(encoding="utf-8").replace("{database}", database)
+
+
+def _safe_relative(value: str, *, allow_empty: bool = False) -> str:
+    if allow_empty and value == "":
+        return ""
+    if not isinstance(value, str) or not value or "\\" in value or ":" in value or value.startswith("/") or value.endswith("/"):
+        raise SyncError("unsafe relative path")
+    parts = value.split("/")
+    if any(part in {"", ".", ".."} for part in parts) or PurePosixPath(value).as_posix() != value:
+        raise SyncError("unsafe relative path")
+    return value
+
+
+def _json_bytes(value: Any) -> bytes:
+    return (canonical_json(value) + "\n").encode("utf-8")
+
+
+def _read_object(data: bytes, label: str) -> dict[str, Any]:
+    try:
+        value = json.loads(data)
+    except (UnicodeError, json.JSONDecodeError, RecursionError) as exc:
+        raise SyncError(f"invalid {label} JSON") from None
+    if not isinstance(value, dict):
+        raise SyncError(f"invalid {label} object")
+    return value
+
+
+def _is_reparse(mode: os.stat_result) -> bool:
+    return stat.S_ISLNK(mode.st_mode) or bool(getattr(mode, "st_file_attributes", 0) & _REPARSE)
+
+
+def _walk_tree(root: Path) -> tuple[set[str], set[str]]:
+    """Inventory regular files and directories, rejecting all reparse points."""
+
+    root_stat = root.lstat()
+    if _is_reparse(root_stat) or not stat.S_ISDIR(root_stat.st_mode):
+        raise SyncError("run directory is a link or non-directory")
+    found_files: set[str] = set()
+    found_dirs: set[str] = set()
+
+    def visit(directory: Path, prefix: str) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                relative = f"{prefix}/{entry.name}" if prefix else entry.name
+                _safe_relative(relative)
+                info = entry.stat(follow_symlinks=False)
+                if _is_reparse(info):
+                    raise SyncError("snapshot contains a link or junction")
+                if stat.S_ISDIR(info.st_mode):
+                    found_dirs.add(relative)
+                    visit(Path(entry.path), relative)
+                elif stat.S_ISREG(info.st_mode):
+                    found_files.add(relative)
+                else:
+                    raise SyncError("snapshot contains a non-regular file")
+
+    visit(root, "")
+    return found_files, found_dirs
+
+
+def _expected_files(root: Path, run_id: str) -> set[str]:
+    manifest = _read_object((root / "manifest.json").read_bytes(), "run manifest")
+    if manifest.get("run_id") != run_id:
+        raise SyncError("run identity changed")
+    capture_ids = manifest.get("capture_ids")
+    if not isinstance(capture_ids, list) or any(not isinstance(cid, str) or not re.fullmatch(r"cap-[A-Za-z0-9]+", cid) for cid in capture_ids):
+        raise SyncError("invalid capture inventory")
+    expected = {"manifest.json"}
+    for cid in capture_ids:
+        base = f"captures/{cid}"
+        expected.update(f"{base}/{name}" for name in ("manifest.json", "events.jsonl", "artifacts.jsonl", "coverage.json"))
+        try:
+            lines = (root / base / "artifacts.jsonl").read_text(encoding="utf-8").splitlines()
+            artifacts = [json.loads(line) for line in lines]
+        except (OSError, UnicodeError, json.JSONDecodeError):
+            raise SyncError("invalid artifact inventory") from None
+        for artifact in artifacts:
+            if not isinstance(artifact, dict):
+                raise SyncError("invalid artifact inventory")
+            path = _safe_relative(artifact.get("path"))
+            if not path.startswith("blobs/"):
+                raise SyncError("invalid artifact path")
+            expected.add(f"{base}/{path}")
+
+    evaluations = root / "evaluations"
+    if evaluations.exists():
+        if not evaluations.is_dir():
+            raise SyncError("invalid evaluations directory")
+        for eval_dir in evaluations.iterdir():
+            evaluation_id = eval_dir.name
+            if not _EVAL_ID.fullmatch(evaluation_id) or not eval_dir.is_dir():
+                raise SyncError("invalid evaluation directory")
+            base = f"evaluations/{evaluation_id}"
+            manifest_path = eval_dir / "manifest.json"
+            if not manifest_path.is_file():
+                raise SyncError("incomplete evaluation directory")
+            evaluation = _read_object(manifest_path.read_bytes(), "evaluation manifest")
+            if evaluation.get("schema_version") != EVALUATION_SCHEMA_VERSION or evaluation.get("run_id") != run_id or evaluation.get("evaluation_id") != evaluation_id:
+                raise SyncError("evaluation identity or schema mismatch")
+            indexed = evaluation.get("files")
+            if not isinstance(indexed, dict) or set(indexed) != {"judgments.jsonl", "metrics.json"}:
+                raise SyncError("evaluation file inventory missing")
+            expected.add(f"{base}/manifest.json")
+            for path, record in indexed.items():
+                _safe_relative(path)
+                if path == "manifest.json" or not isinstance(record, dict) or set(record) != {"sha256", "size_bytes"}:
+                    raise SyncError("invalid evaluation inventory item")
+                digest, size = record["sha256"], record["size_bytes"]
+                if not isinstance(digest, str) or not _DIGEST.fullmatch(digest) or type(size) is not int or size < 0:
+                    raise SyncError("invalid evaluation digest or size")
+                relative = f"{base}/{path}"
+                data = (root / relative).read_bytes()
+                if sha256_bytes(data) != digest or len(data) != size:
+                    raise SyncError("evaluation file hash or size mismatch")
+                expected.add(relative)
+            metrics = _read_object((eval_dir / "metrics.json").read_bytes(), "metrics")
+            if metrics.get("schema_version") != "sphynx.metrics.v1" or metrics.get("run_id") != run_id or metrics.get("evaluation_id") != evaluation_id:
+                raise SyncError("metrics identity or schema mismatch")
+            try:
+                judgments = [json.loads(line) for line in (eval_dir / "judgments.jsonl").read_text(encoding="utf-8").splitlines()]
+            except (OSError, UnicodeError, json.JSONDecodeError):
+                raise SyncError("invalid judgments") from None
+            if any(not isinstance(row, dict) or row.get("schema_version") != "sphynx.judgment.v1" or row.get("run_id") != run_id or row.get("evaluation_id") != evaluation_id for row in judgments):
+                raise SyncError("judgment identity or schema mismatch")
+            # The grader owns the semantic judgment/aggregate contract. A
+            # self-consistent hash inventory alone cannot prove that counts,
+            # releases, case identities, and aggregate metrics are correct.
+            from .results import verify_evaluation
+
+            try:
+                verify_evaluation(eval_dir)
+            except Exception:
+                raise SyncError("evaluation semantic validation failed") from None
+    return expected
+
+
+def _validate_tree(root: Path, run_id: str) -> list[dict[str, Any]]:
+    found, directories = _walk_tree(root)
+    from .results import _verify_gradable_run
+
+    _verify_gradable_run(RunRef(run_id, root, "rag.rerank.v1"))
+    expected = _expected_files(root, run_id)
+    expected_dirs = {str(PurePosixPath(path).parent) for path in expected if "/" in path}
+    expected_dirs |= {str(parent) for path in expected for parent in PurePosixPath(path).parents if str(parent) != "."}
+    if found != expected or directories != expected_dirs:
+        raise SyncError("snapshot has missing, extra, or unindexed files or directories")
+    return [
+        {"path": path, "size_bytes": len(data), "sha256": sha256_bytes(data)}
+        for path in sorted(found)
+        for data in [(root / Path(*path.split("/"))).read_bytes()]
+    ]
+
+
+def _stage_snapshot(ref: RunRef) -> tuple[bytes, str, Path, tempfile.TemporaryDirectory[str]]:
+    original_inventory = _validate_tree(ref.path, ref.run_id)
+    temporary = tempfile.TemporaryDirectory(prefix="sphynx-snapshot-")
+    staged = Path(temporary.name) / "runs" / ref.run_id
+    staged.mkdir(parents=True)
+    try:
+        for item in original_inventory:
+            relative = Path(*item["path"].split("/"))
+            destination = staged / relative
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            source = ref.path / relative
+            before = source.lstat()
+            if _is_reparse(before) or not stat.S_ISREG(before.st_mode):
+                raise SyncError("source changed during snapshot")
+            data = source.read_bytes()
+            after = source.lstat()
+            if before.st_size != after.st_size or before.st_mtime_ns != after.st_mtime_ns or sha256_bytes(data) != item["sha256"]:
+                raise SyncError("source changed during snapshot")
+            destination.write_bytes(data)
+        # Both trees must still contain exactly the same bytes and inventory.
+        if _validate_tree(ref.path, ref.run_id) != original_inventory or _validate_tree(staged, ref.run_id) != original_inventory:
+            raise SyncError("source changed during snapshot")
+        snapshot = {"schema_version": SNAPSHOT_SCHEMA, "run_id": ref.run_id, "files": original_inventory}
+        snapshot_bytes = _json_bytes(snapshot)
+        bundle_digest = sha256_bytes(snapshot_bytes)
+        archive = _make_archive(staged, snapshot_bytes, original_inventory)
+        _check_archive(archive, bundle_digest)
+        return archive, bundle_digest, staged, temporary
+    except BaseException:
+        temporary.cleanup()
+        raise
+
+
+def _make_archive(staged: Path, snapshot_bytes: bytes, inventory: list[dict[str, Any]]) -> bytes:
+    output = io.BytesIO()
+    with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_STORED, allowZip64=True) as archive:
+        for name, data in [("snapshot.json", snapshot_bytes)] + [
+            (item["path"], (staged / Path(*item["path"].split("/"))).read_bytes()) for item in inventory
+        ]:
+            info = zipfile.ZipInfo(name, (1980, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_STORED
+            info.external_attr = 0o100644 << 16
+            info.create_system = 3
+            archive.writestr(info, data)
+    return output.getvalue()
+
+
+def _check_archive(data: bytes, bundle_digest: str) -> dict[str, Any]:
+    try:
+        with zipfile.ZipFile(io.BytesIO(data), "r") as archive:
+            names = archive.namelist()
+            if len(names) != len(set(names)) or not names or names[0] != "snapshot.json":
+                raise SyncError("invalid archive inventory")
+            if archive.comment or any(
+                info.date_time != (1980, 1, 1, 0, 0, 0)
+                or info.compress_type != zipfile.ZIP_STORED
+                or info.external_attr != 0o100644 << 16
+                or info.extra or info.comment
+                for info in archive.infolist()
+            ):
+                raise SyncError("archive metadata is not normalized")
+            snapshot_bytes = archive.read("snapshot.json")
+            if sha256_bytes(snapshot_bytes) != bundle_digest:
+                raise SyncError("bundle digest mismatch")
+            snapshot = _read_object(snapshot_bytes, "snapshot")
+            if snapshot_bytes != _json_bytes(snapshot):
+                raise SyncError("snapshot JSON is not canonical")
+            if snapshot.get("schema_version") != SNAPSHOT_SCHEMA or not isinstance(snapshot.get("run_id"), str):
+                raise SyncError("unsupported snapshot")
+            inventory = snapshot.get("files")
+            if not isinstance(inventory, list) or names[1:] != [item.get("path") for item in inventory if isinstance(item, dict)] or names[1:] != sorted(names[1:]):
+                raise SyncError("archive file inventory mismatch")
+            for item in inventory:
+                if not isinstance(item, dict) or set(item) != {"path", "size_bytes", "sha256"}:
+                    raise SyncError("invalid snapshot entry")
+                path = _safe_relative(item["path"])
+                payload = archive.read(path)
+                if type(item["size_bytes"]) is not int or len(payload) != item["size_bytes"] or sha256_bytes(payload) != item["sha256"]:
+                    raise SyncError("archive file hash or size mismatch")
+            return snapshot
+    except (zipfile.BadZipFile, KeyError, OSError, ValueError, RecursionError):
+        raise SyncError("invalid archive bytes") from None
+
+
+def _projection_id(run_id: str, bundle_digest: str) -> str:
+    return "projection-" + hashlib.sha256(canonical_json([PROJECTION_SCHEMA, run_id, bundle_digest]).encode("utf-8")).hexdigest()
+
+
+def _fact(projection_id: str, run_id: str, fact_type: str, key: list[str], payload: Mapping[str, Any]) -> FactRow:
+    payload_json = canonical_json(dict(payload))
+    row_id = "fact-" + hashlib.sha256(canonical_json([fact_type, key]).encode("utf-8")).hexdigest()
+    row_hash = sha256_bytes(canonical_json([fact_type, payload_json]).encode("utf-8"))
+    value = payload.get("value")
+    numeric = float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+    return FactRow(
+        projection_id, row_id, row_hash, fact_type, run_id,
+        str(payload.get("case_id") or ""), str(payload.get("capture_id") or ""),
+        str(payload.get("evaluation_id") or ""), str(payload.get("metric_id") or ""),
+        str(payload.get("capability_id") or ""), str(payload.get("status") or ""), numeric, payload_json,
+    )
+
+
+def _facts(staged: Path, projection_id: str) -> list[FactRow]:
+    run = _read_object((staged / "manifest.json").read_bytes(), "run")
+    run_id = run["run_id"]
+    facts: list[FactRow] = []
+    facts.append(_fact(projection_id, run_id, "run", [run_id], {
+        "run_id": run_id, "pack_id": run.get("pack_id"), "pack_release": run.get("pack_release"),
+        "track": run.get("track"), "candidate": run.get("candidate"), "trust_tier": run.get("trust_tier"),
+        "status": run.get("status"), "case_count": run.get("case_count"), "capture_count": run.get("capture_count"),
+        "success_count": run.get("success_count"), "failure_count": run.get("failure_count"),
+    }))
+    for case in run["cases"]:
+        facts.append(_fact(projection_id, run_id, "case", [run_id, case["case_id"]], {"run_id": run_id, **case}))
+    for capture_id in run["capture_ids"]:
+        base = staged / "captures" / capture_id
+        capture = _read_object((base / "manifest.json").read_bytes(), "capture")
+        identity = capture["identity"]
+        facts.append(_fact(projection_id, run_id, "capture", [run_id, capture_id], {
+            "run_id": run_id, "capture_id": capture_id, "case_id": identity["case_id"],
+            "trial_index": identity["trial_index"], "attempt_index": identity["attempt_index"],
+            "pool_digest": identity["pool_digest"], "status": capture["status"],
+            "failure_code": capture.get("failure_code"), "elapsed_ns": capture["timing"]["elapsed_ns"],
+            "candidate_latency_ns": capture["timing"].get("candidate_latency_ns"),
+        }))
+        coverage = _read_object((base / "coverage.json").read_bytes(), "coverage")
+        for capability in coverage["capabilities"]:
+            capability_id = capability["capability_id"]
+            facts.append(_fact(projection_id, run_id, "capability", [run_id, capture_id, capability_id], {
+                "run_id": run_id, "capture_id": capture_id, "case_id": identity["case_id"],
+                "capability_id": capability_id, "capability_schema_version": capability["capability_schema_version"],
+                "status": capability["state"], "observed_count": capability["observed_count"],
+            }))
+    evaluations = staged / "evaluations"
+    if evaluations.exists():
+        for directory in sorted(evaluations.iterdir()):
+            manifest = _read_object((directory / "manifest.json").read_bytes(), "evaluation")
+            eid = manifest["evaluation_id"]
+            facts.append(_fact(projection_id, run_id, "evaluation", [run_id, eid], {
+                "run_id": run_id, "evaluation_id": eid, "schema_version": manifest["schema_version"],
+                "grader_release": manifest.get("grader_release"), "metric_release": manifest.get("metric_release"),
+                "status": manifest.get("status", "completed"),
+            }))
+            metrics = _read_object((directory / "metrics.json").read_bytes(), "metrics")
+            facts.extend(_metric_facts(projection_id, run_id, eid, metrics))
+            for line in (directory / "judgments.jsonl").read_text(encoding="utf-8").splitlines():
+                judgment = json.loads(line)
+                values = judgment.get("values")
+                if not isinstance(values, dict):
+                    raise SyncError("judgment metric values missing")
+                case_id = judgment["case_id"]
+                for metric_id, value in values.items():
+                    if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float)) or not float("-inf") < float(value) < float("inf")):
+                        raise SyncError("invalid judgment metric value")
+                    facts.append(_fact(projection_id, run_id, "metric", [run_id, eid, "case", case_id, metric_id], {
+                        "run_id": run_id, "evaluation_id": eid, "case_id": case_id,
+                        "capture_id": judgment.get("capture_id"), "scope": "case", "metric_id": metric_id,
+                        "value": value, "status": judgment["status"] if value is None else "available",
+                    }))
+    ids = [fact.row_id for fact in facts]
+    if len(ids) != len(set(ids)):
+        raise SyncError("duplicate logical fact identity")
+    return sorted(facts, key=lambda fact: fact.row_id)
+
+
+def _metric_facts(projection_id: str, run_id: str, evaluation_id: str, metrics: Mapping[str, Any]) -> list[FactRow]:
+    """Project every versioned aggregate, preserving missingness counts."""
+    out: list[FactRow] = []
+    values = metrics.get("metrics")
+    if not isinstance(values, dict):
+        raise SyncError("aggregate metrics missing")
+    for metric_id, entry in sorted(values.items()):
+        if not isinstance(metric_id, str) or not metric_id or not isinstance(entry, dict) or entry.get("metric_id") != metric_id:
+            raise SyncError("invalid aggregate metric")
+        value = entry.get("value")
+        if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float)) or not float("-inf") < float(value) < float("inf")):
+            raise SyncError("non-finite or invalid metric")
+        payload = {"run_id": run_id, "evaluation_id": evaluation_id, "case_id": "", "scope": "aggregate",
+                   "metric_id": metric_id, "release": entry.get("release"), "unit": entry.get("unit"),
+                   "direction": entry.get("direction"), "value": value,
+                   "p95": entry.get("p95"), "eligible_count": entry.get("eligible_count"),
+                   "observed_count": entry.get("observed_count"), "missing_count": entry.get("missing_count"),
+                   "undefined_count": entry.get("undefined_count"), "complete": entry.get("complete"),
+                   "status": "available" if value is not None else "undefined"}
+        out.append(_fact(projection_id, run_id, "metric", [run_id, evaluation_id, "aggregate", "", metric_id], payload))
+    return out
+
+
+def _fact_summary(rows: list[FactRow]) -> tuple[dict[str, int], str]:
+    counts: dict[str, int] = {}
+    for row in rows:
+        counts[row.fact_type] = counts.get(row.fact_type, 0) + 1
+    digest = sha256_bytes(canonical_json([[row.row_id, row.row_hash] for row in sorted(rows, key=lambda row: row.row_id)]).encode("utf-8"))
+    return counts, digest
+
+
+def _gate_facts(expected: list[FactRow], physical: list[FactRow]) -> None:
+    by_id: dict[str, FactRow] = {}
+    for row in physical:
+        if row.row_hash != sha256_bytes(canonical_json([row.fact_type, row.payload_json]).encode("utf-8")):
+            raise SyncError("stored fact hash mismatch")
+        prior = by_id.setdefault(row.row_id, row)
+        if prior != row:
+            raise SyncError("conflicting duplicate fact")
+    expected_map = {row.row_id: row for row in expected}
+    if by_id != expected_map:
+        raise SyncError("missing, extra, or altered facts")
+    if _fact_summary(list(by_id.values())) != _fact_summary(expected):
+        raise SyncError("fact count or digest mismatch")
+
+
+def _commit(projection_id: str, run_id: str, bundle_digest: str, uri: str, generation: str, archive_sha: str, facts: list[FactRow]) -> CommitRow:
+    counts, fact_digest = _fact_summary(facts)
+    payload = {"schema_version": COMMIT_SCHEMA, "projection_id": projection_id, "run_id": run_id,
+               "bundle_digest": bundle_digest, "archive_uri": uri, "archive_generation": generation,
+               "archive_sha256": archive_sha, "fact_counts": counts, "fact_digest": fact_digest}
+    content = canonical_json(payload)
+    return CommitRow(projection_id, sha256_bytes(content.encode("utf-8")), content)
+
+
+def _gate_commits(expected: CommitRow, physical: list[CommitRow]) -> None:
+    if not physical:
+        raise SyncError("projection has no commit")
+    for row in physical:
+        if row != expected or row.commit_hash != sha256_bytes(row.payload_json.encode("utf-8")):
+            raise SyncError("conflicting or corrupt commit")
+
+
+def _key(config: StorageConfig, run_id: str, digest: str) -> str:
+    stem = f"runs/{run_id}/snapshots/{digest}"
+    return f"{config.gcs_prefix}/{stem}" if config.gcs_prefix else stem
+
+
+def _archive_gate(store: ArchiveStore, key: str, generation: str, expected_bytes: bytes, digest: str) -> None:
+    stored = store.read_generation(key, generation)
+    if stored != expected_bytes or sha256_bytes(stored) != sha256_bytes(expected_bytes):
+        raise SyncError("stored archive bytes differ from closed snapshot")
+    _check_archive(stored, digest)
+
+
+def _pending(stage: str, reason: str, projection_id: str | None = None, digest: str | None = None, uri: str | None = None, generation: str | None = None) -> SyncResult:
+    return SyncResult("pending", projection_id, digest, uri, generation, stage, reason)
+
+
+def sync(run_ref: RunRef | str | Path, storage_config: StorageConfig, *, archive_store: ArchiveStore | None = None, fact_store: FactStore | None = None) -> SyncResult:
+    """Archive a validated closed snapshot, then commit visible facts last.
+
+    A pending result is safe to retry. Local validation and staging precede all
+    remote operations. Existing physical duplicates are accepted only when
+    every row is byte-equivalent to its deterministic expected logical row.
+    """
+
+    if not isinstance(storage_config, StorageConfig):
+        raise TypeError("storage_config must be StorageConfig")
+    temporary: tempfile.TemporaryDirectory[str] | None = None
+    try:
+        raw_path = run_ref.path if isinstance(run_ref, RunRef) else Path(run_ref)
+        absolute_path = Path(raw_path).expanduser().absolute()
+        if _is_reparse(absolute_path.lstat()):
+            raise SyncError("run path is a link or junction")
+        _walk_tree(absolute_path)
+        ref = open_run(run_ref)
+        if not _RUN_ID.fullmatch(ref.run_id):
+            raise SyncError("invalid run ID for projection")
+        archive, digest, staged, temporary = _stage_snapshot(ref)
+        projection_id = _projection_id(ref.run_id, digest)
+        facts = _facts(staged, projection_id)
+    except Exception:
+        if temporary is not None:
+            temporary.cleanup()
+        return _pending("local_validation", "invalid_or_changing_snapshot")
+    try:
+        try:
+            gcs = archive_store if archive_store is not None else GCSArchiveStore(storage_config)
+            clickhouse = fact_store if fact_store is not None else ClickHouseFactStore(storage_config)
+        except Exception:
+            return _pending("configuration", "transport_unavailable", projection_id, digest)
+        key = _key(storage_config, ref.run_id, digest)
+        uri = f"gs://{storage_config.gcs_bucket}/{key}"
+        generation: str | None = None
+        try:
+            generation = gcs.put_create_only(key, archive)
+        except Exception:
+            # A lost response may follow successful creation. Fetch the current
+            # immutable generation and compare exact bytes before continuing.
+            try:
+                generation = gcs.latest_generation(key)
+            except Exception:
+                pass
+        if generation is None:
+            return _pending("archive", "upload_or_lookup_failed", projection_id, digest, uri)
+        if not isinstance(generation, str) or not _GENERATION.fullmatch(generation):
+            return _pending("archive", "invalid_archive_generation", projection_id, digest, uri)
+        try:
+            _archive_gate(gcs, key, generation, archive, digest)
+        except Exception:
+            return _pending("archive", "archive_readback_failed_or_conflicted", projection_id, digest, uri, generation)
+        expected_commit = _commit(projection_id, ref.run_id, digest, uri, generation, sha256_bytes(archive), facts)
+        try:
+            existing = clickhouse.read_commits(projection_id)
+            if existing:
+                _gate_commits(expected_commit, existing)
+                _gate_facts(facts, clickhouse.read_facts(projection_id))
+                return SyncResult("committed", projection_id, digest, uri, generation)
+        except Exception:
+            return _pending("commit_read", "existing_commit_invalid_or_unavailable", projection_id, digest, uri, generation)
+        try:
+            clickhouse.insert_facts(facts)
+            _gate_facts(facts, clickhouse.read_facts(projection_id))
+        except Exception:
+            return _pending("facts", "insert_or_readback_failed", projection_id, digest, uri, generation)
+        try:
+            clickhouse.insert_commit(expected_commit)
+        except Exception:
+            # A response may be lost after insertion; the same full gate below
+            # determines whether the projection became visible.
+            pass
+        try:
+            _gate_commits(expected_commit, clickhouse.read_commits(projection_id))
+            _gate_facts(facts, clickhouse.read_facts(projection_id))
+            _archive_gate(gcs, key, generation, archive, digest)
+        except Exception:
+            return _pending("commit", "commit_or_final_gate_failed", projection_id, digest, uri, generation)
+        return SyncResult("committed", projection_id, digest, uri, generation)
+    finally:
+        assert temporary is not None
+        temporary.cleanup()
+
+
+def read_committed_projection(projection_id: str, storage_config: StorageConfig, *, archive_store: ArchiveStore | None = None, fact_store: FactStore | None = None) -> SyncResult | None:
+    """Read only a projection whose archived snapshot, facts, and commit agree.
+
+    The archive is the authoritative snapshot for historical reads. A later
+    local regrade does not hide or mutate an earlier committed projection.
+    ``None`` means absent or invalid; callers must never expose raw fact rows.
+    """
+    if not isinstance(storage_config, StorageConfig):
+        raise TypeError("storage_config must be StorageConfig")
+    temporary: tempfile.TemporaryDirectory[str] | None = None
+    try:
+        gcs = archive_store if archive_store is not None else GCSArchiveStore(storage_config)
+        clickhouse = fact_store if fact_store is not None else ClickHouseFactStore(storage_config)
+        commits = clickhouse.read_commits(projection_id)
+        if not commits:
+            return None
+        first = commits[0]
+        if first.commit_hash != sha256_bytes(first.payload_json.encode("utf-8")):
+            return None
+        parsed = _read_object(first.payload_json.encode("utf-8"), "commit")
+        run_id, digest, generation, archive_sha = (
+            parsed.get("run_id"), parsed.get("bundle_digest"), parsed.get("archive_generation"), parsed.get("archive_sha256")
+        )
+        if (parsed.get("schema_version") != COMMIT_SCHEMA or parsed.get("projection_id") != projection_id
+                or not isinstance(run_id, str) or not _RUN_ID.fullmatch(run_id)
+                or not isinstance(digest, str) or not _DIGEST.fullmatch(digest)
+                or not isinstance(generation, str) or not _GENERATION.fullmatch(generation)
+                or not isinstance(archive_sha, str) or not _DIGEST.fullmatch(archive_sha)
+                or _projection_id(run_id, digest) != projection_id):
+            return None
+        key = _key(storage_config, run_id, digest)
+        uri = f"gs://{storage_config.gcs_bucket}/{key}"
+        if parsed.get("archive_uri") != uri:
+            return None
+        archive = gcs.read_generation(key, generation)
+        if sha256_bytes(archive) != archive_sha:
+            return None
+        snapshot = _check_archive(archive, digest)
+        if snapshot["run_id"] != run_id:
+            return None
+        temporary = tempfile.TemporaryDirectory(prefix="sphynx-read-")
+        staged = Path(temporary.name) / "runs" / run_id
+        staged.mkdir(parents=True)
+        with zipfile.ZipFile(io.BytesIO(archive), "r") as zip_file:
+            for item in snapshot["files"]:
+                relative = _safe_relative(item["path"])
+                path = staged / Path(*relative.split("/"))
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_bytes(zip_file.read(relative))
+        if _validate_tree(staged, run_id) != snapshot["files"]:
+            return None
+        facts = _facts(staged, projection_id)
+        expected = _commit(projection_id, run_id, digest, uri, generation, archive_sha, facts)
+        _gate_commits(expected, commits)
+        _gate_facts(facts, clickhouse.read_facts(projection_id))
+        return SyncResult("committed", projection_id, digest, uri, generation)
+    except Exception:
+        return None
+    finally:
+        if temporary is not None:
+            temporary.cleanup()
+
+
+class GCSArchiveStore:
+    """Lazy google-cloud-storage adapter using keyless or named credentials."""
+
+    def __init__(self, config: StorageConfig) -> None:
+        try:
+            from google.cloud import storage  # type: ignore[import-not-found]
+
+            if config.gcs_service_account_json is not None:
+                service_account = json.loads(config.gcs_service_account_json)
+                if not isinstance(service_account, dict) or service_account.get("client_email") != config.gcs_identity:
+                    raise ValueError("GCS identity mismatch")
+                client = storage.Client.from_service_account_info(service_account)
+            else:
+                import google.auth  # type: ignore[import-not-found]
+
+                credentials, project = google.auth.default(scopes=["https://www.googleapis.com/auth/devstorage.read_write"])
+                observed_email = getattr(credentials, "service_account_email", None)
+                # Compute metadata credentials can report "default" until refresh.
+                # Resolve that alias before accepting a principal for this sink.
+                if observed_email == "default":
+                    from google.auth.transport.requests import Request  # type: ignore[import-not-found]
+
+                    credentials.refresh(Request())
+                    observed_email = getattr(credentials, "service_account_email", None)
+                if observed_email != config.gcs_identity:
+                    raise ValueError("GCS identity mismatch")
+                client = storage.Client(project=project, credentials=credentials)
+            self._bucket = client.bucket(config.gcs_bucket)
+        except Exception:
+            raise SyncTransportError("GCS adapter unavailable or identity invalid") from None
+
+    def put_create_only(self, key: str, data: bytes) -> str:
+        try:
+            blob = self._bucket.blob(key)
+            blob.upload_from_string(data, content_type="application/zip", if_generation_match=0)
+            return str(blob.generation)
+        except Exception:
+            raise SyncTransportError("GCS create-only upload failed") from None
+
+    def latest_generation(self, key: str) -> str | None:
+        try:
+            blob = self._bucket.get_blob(key)
+            return str(blob.generation) if blob is not None else None
+        except Exception:
+            raise SyncTransportError("GCS generation lookup failed") from None
+
+    def read_generation(self, key: str, generation: str) -> bytes:
+        try:
+            return self._bucket.blob(key, generation=int(generation)).download_as_bytes()
+        except Exception:
+            raise SyncTransportError("GCS generation read failed") from None
+
+
+class ClickHouseFactStore:
+    """HTTPS JSONEachRow adapter; sync needs INSERT and SELECT only."""
+
+    def __init__(self, config: StorageConfig) -> None:
+        self._config = config
+        token = f"{config.clickhouse_user}:{config.clickhouse_password}".encode("utf-8")
+        self._authorization = "Basic " + base64.b64encode(token).decode("ascii")
+        self._url = config.clickhouse_url.rstrip("/") + "/"
+        self._database = config.clickhouse_database
+
+    def _post(self, sql: str) -> bytes:
+        request = urllib.request.Request(self._url, sql.encode("utf-8"), headers={
+            "Authorization": self._authorization, "Content-Type": "text/plain; charset=utf-8",
+        }, method="POST")
+        try:
+            with open_no_redirect(request, timeout=30) as response:
+                return response.read()
+        except Exception:
+            raise SyncTransportError("ClickHouse request failed") from None
+
+    def _insert(self, table: str, rows: list[dict[str, Any]]) -> None:
+        body = "".join(canonical_json(row) + "\n" for row in rows)
+        self._post(f"INSERT INTO {self._database}.{table} FORMAT JSONEachRow\n" + body)
+
+    def _select(self, table: str, projection_id: str) -> list[dict[str, Any]]:
+        if not re.fullmatch(r"projection-[0-9a-f]{64}", projection_id):
+            raise SyncError("invalid projection ID")
+        raw = self._post(f"SELECT * FROM {self._database}.{table} WHERE projection_id = '{projection_id}' FORMAT JSONEachRow")
+        try:
+            return [json.loads(line) for line in raw.decode("utf-8").splitlines() if line]
+        except (UnicodeError, json.JSONDecodeError):
+            raise SyncTransportError("ClickHouse response invalid") from None
+
+    def insert_facts(self, rows: list[FactRow]) -> None:
+        self._insert("sphynx_facts_v1", [row.to_dict() for row in rows])
+
+    def read_facts(self, projection_id: str) -> list[FactRow]:
+        try:
+            return [FactRow(**row) for row in self._select("sphynx_facts_v1", projection_id)]
+        except (TypeError, ValueError):
+            raise SyncTransportError("ClickHouse fact row invalid") from None
+
+    def insert_commit(self, row: CommitRow) -> None:
+        self._insert("sphynx_projection_commits_v1", [row.to_dict()])
+
+    def read_commits(self, projection_id: str) -> list[CommitRow]:
+        try:
+            return [CommitRow(**row) for row in self._select("sphynx_projection_commits_v1", projection_id)]
+        except (TypeError, ValueError):
+            raise SyncTransportError("ClickHouse commit row invalid") from None