socialcli 0.3.0__py3-none-any.whl

socialctl/metricas/analytics_client.py

@@ -0,0 +1,304 @@
+"""Bounded account reads and fixed Analytics transport; no credential refresh."""
+from datetime import timedelta
+import json
+import re
+import time
+from urllib.parse import quote
+
+import httpx
+
+from socialctl.identity import credential_metadata
+from socialctl.management.youtube_owned import YouTubeOwnedClient
+from socialctl.management.youtube_resources import API, ResourceError, ResourceRejected, ResourceUncertain, provider_reason, resource_id
+from socialctl.metricas.analytics_schema import ReportQuery, parse_query_response, provenance, metric_value
+from socialctl.models import Platform
+
+ANALYTICS = "https://youtubeanalytics.googleapis.com/v2"
+REPORTING = "https://youtubereporting.googleapis.com/v1"
+
+
+def opaque(value):
+    if not isinstance(value, str) or not 1 <= len(value) <= 512 or any(ord(c) < 33 or ord(c) == 127 for c in value):
+        raise ResourceError("invalid opaque provider ID")
+    return value
+
+
+def encoded(value):
+    return quote(opaque(value), safe="")
+
+
+def complete(result):
+    if not result["complete"]:
+        raise ResourceError("incomplete provider list; absence/ownership not established")
+    return result["items"]
+
+
+def unsigned_long(value):
+    """Exact documented unsigned long; preserve caller's raw wire value."""
+    if type(value) is int:
+        number = value
+    elif isinstance(value, str) and re.fullmatch(r"[0-9]{1,20}", value):
+        number = int(value)
+    else:
+        raise ResourceError("unsigned long schema invalid")
+    if not 0 <= number <= 18446744073709551615:
+        raise ResourceError("unsigned long outside uint64 range")
+    return number
+
+
+def failure(exc):
+    if exc.http_status == 400:
+        return "provider_rejected_report_combination"
+    if exc.http_status == 429 or exc.provider_reason == "quotaExceeded":
+        return "rate_limited"
+    if exc.http_status in {401, 403}:
+        return "forbidden_or_missing_grant"
+    return "provider_or_schema_unavailable"
+
+
+class AnalyticsClient(YouTubeOwnedClient):
+    def _token(self):
+        if self._access_token is None:
+            try:
+                secret = self.brand.leer_secreto(Platform.YOUTUBE)
+                self.credential_observation = credential_metadata(secret)
+                if secret.get("auth_mode") == "broker":
+                    from socialctl.connections.client import broker_access_token
+                    token = broker_access_token(self.brand, Platform.YOUTUBE, self.client, refresh=False)
+                else:
+                    token = secret.get("access_token")
+            except Exception:
+                raise ResourceError("credentials unavailable") from None
+            if self.credential_observation["expiry"]["expired"]:
+                raise ResourceError("credentials expired; no implicit refresh")
+            if not isinstance(token, str) or not token:
+                raise ResourceError("credentials unavailable")
+            self._access_token = token
+        return self._access_token
+
+    def require_scope(self, scopes):
+        self._token()
+        actual = self.credential_observation["granted_scopes"]
+        if actual["state"] != "known" or not set(actual["values"]) & set(scopes):
+            raise ResourceError("required granted scope not recorded; no new grant or refresh attempted")
+
+    def _endpoint_allowed(self, method, path):
+        return method == "GET" and path in {"/youtube/v3/channels", "/youtube/v3/videos", "/youtube/v3/playlists", "/youtube/v3/videos:batchGetStats"}
+
+    def service_request(self, method, url, *, max_bytes=4*1024*1024, **kwargs):
+        parsed = httpx.URL(url)
+        paths = {("GET", "/v2/reports"), *( (m, "/v2/" + r) for r in ("groups", "groupItems") for m in ("GET", "POST", "PUT", "DELETE") if not (r == "groupItems" and m == "PUT") )}
+        reporting = ((method, parsed.path) in {("GET", "/v1/reportTypes"), ("GET", "/v1/jobs"), ("POST", "/v1/jobs")}
+            or method in {"GET", "DELETE"} and bool(re.fullmatch(r"/v1/jobs/[^/]+", parsed.path))
+            or method == "GET" and bool(re.fullmatch(r"/v1/jobs/[^/]+/reports(?:/[^/]+)?", parsed.path)))
+        allowed = (parsed.host == "youtubeanalytics.googleapis.com" and (method, parsed.path) in paths
+            or parsed.host == "youtubereporting.googleapis.com" and reporting
+            or parsed.host == "www.googleapis.com" and method == "GET" and parsed.path == "/youtube/v3/videos:batchGetStats")
+        if not allowed or parsed.scheme != "https" or parsed.port not in {None, 443} or parsed.userinfo or parsed.query or parsed.fragment:
+            raise ResourceError("endpoint not allowed")
+        return self._bounded_request(method, url, max_bytes=max_bytes, **kwargs)
+
+    def _bounded_request(self, method, url, *, max_bytes, **kwargs):
+        token = self._token()
+        writing = method != "GET"
+        deadline = time.monotonic() + 120
+        try:
+            with self.client.stream(method, url, headers={"Authorization": f"Bearer {token}", "Accept-Encoding": "identity"},
+                follow_redirects=False, timeout=60, **kwargs) as response:
+                if not response.is_success:
+                    error = (ResourceUncertain if response.is_redirect or response.status_code >= 500 else ResourceRejected) if writing else ResourceError
+                    reason = provider_reason(response, token)
+                    raise error(f"provider HTTP {response.status_code}; effect unconfirmed", http_status=response.status_code, provider_reason=reason)
+                if response.headers.get("content-encoding", "identity") != "identity":
+                    raise (ResourceUncertain if writing else ResourceError)("compressed response not accepted")
+                if not writing and response.status_code != 200:
+                    raise ResourceError("partial/nonstandard read response not accepted")
+                length = response.headers.get("content-length")
+                if length is not None and (not re.fullmatch(r"[0-9]{1,12}", length) or int(length) > max_bytes):
+                    raise (ResourceUncertain if writing else ResourceError)("invalid response length or byte limit exceeded")
+                raw = bytearray()
+                for chunk in response.iter_bytes(chunk_size=65536):
+                    if len(raw)+len(chunk) > max_bytes or time.monotonic() > deadline:
+                        raise (ResourceUncertain if writing else ResourceError)("response byte limit")
+                    raw.extend(chunk)
+                if length is not None and len(raw) != int(length):
+                    raise (ResourceUncertain if writing else ResourceError)("partial response length mismatch")
+                return httpx.Response(response.status_code, content=bytes(raw), request=response.request)
+        except ResourceError:
+            raise
+        except Exception:
+            raise (ResourceUncertain if writing else ResourceError)("provider transport interrupted") from None
+
+    def pages(self, url, key="items", params=None, max_pages=100, paginated=True):
+        if type(max_pages) is not int or not 1 <= max_pages <= 100:
+            raise ResourceError("page bound 1..100")
+        items, seen, ids = [], set(), set()
+        params = dict(params or {})
+        result = {"items": items, "complete": False, "failure_reason": None, "pages": 0}
+        for _ in range(max_pages):
+            try:
+                payload = self._json(self.service_request("GET", url, params=params))
+                if key not in payload and (key == "items" or set(payload)-{"nextPageToken"}):
+                    raise ResourceError("list envelope schema missing collection")
+                rows = payload.get(key, [])
+                if not isinstance(rows, list) or len(rows) > 1000 or len(items)+len(rows) > 100000:
+                    raise ResourceError("invalid/oversized provider page")
+                page_ids = [opaque(r.get("id")) if isinstance(r, dict) else opaque(None) for r in rows]
+                if len(page_ids) != len(set(page_ids)) or set(page_ids) & ids:
+                    raise ResourceError("duplicate identity across provider pages")
+                token = payload.get("nextPageToken")
+                if "nextPageToken" in payload and (not paginated or not isinstance(token, str) or not token or len(token) > 4096 or token in seen):
+                    raise ResourceError("invalid/repeated pagination token")
+                items.extend(rows)
+                ids.update(page_ids)
+                result["pages"] += 1
+                if token is None:
+                    result["complete"] = True
+                    return result
+                seen.add(token)
+                params["pageToken"] = token
+            except ResourceError as exc:
+                result["failure_reason"] = failure(exc)
+                return result
+        result["failure_reason"] = "page_limit"
+        return result
+
+    def groups(self, max_pages=100):
+        self.identity()
+        result = self.pages(f"{ANALYTICS}/groups", params={"mine": "true"}, max_pages=max_pages)
+        for row in result["items"]:
+            if not isinstance(row.get("snippet"), dict) or not isinstance(row["snippet"].get("title"), str) or not isinstance(row.get("contentDetails"), dict) or row["contentDetails"].get("itemType") not in {"youtube#video", "youtube#channel", "youtube#playlist", "youtubePartner#asset"}:
+                raise ResourceError("group schema invalid")
+        return result
+
+    def group(self, group_id):
+        rows = [r for r in complete(self.groups()) if r["id"] == opaque(group_id)]
+        if len(rows) != 1:
+            raise ResourceError("group not verified in authenticated mine membership")
+        return rows[0]
+
+    def group_items(self, group_id):
+        self.group(group_id)
+        result = self.pages(f"{ANALYTICS}/groupItems", params={"groupId": opaque(group_id)}, paginated=False)
+        for row in result["items"]:
+            if row.get("groupId") != group_id or not isinstance(row.get("resource"), dict):
+                raise ResourceError("groupItems identity mismatch")
+            opaque(row["resource"].get("id"))
+        return result
+
+    def bind_group_resource(self, group, rid):
+        kind = group["contentDetails"]["itemType"]
+        if kind == "youtube#video":
+            return self.one("videos", resource_id(rid), parts="snippet")
+        if kind == "youtube#channel" and rid == self.identity():
+            return {"id": rid}
+        if kind == "youtube#playlist":
+            return self.one("playlists", resource_id(rid))
+        raise ResourceError("resource not owned or content-owner asset unsupported")
+
+    def query(self, query):
+        query = ReportQuery.model_validate(query.model_dump())
+        account = self.identity()
+        for vid in query.video_ids:
+            self.one("videos", vid, parts="snippet")
+        for playlist in query.playlist_ids:
+            self.one("playlists", playlist)
+        if query.group_id:
+            self.group(query.group_id)
+        result = {"query": query.model_dump(mode="json"), "rows": [], "complete": False, "failure_reason": None,
+            "provenance": provenance("youtubeAnalytics.reports.query", account), "pages": 0}
+        result["provenance"]["dimensions"] = query.dimensions
+        result["provenance"]["paid_organic_eligibility"] = query.audience_type or "report_metric_dependent_not_inferred"
+        result["provenance"]["credential_observation"] = self.credential_observation
+        params, seen = query.params(), set()
+        for _ in range(query.max_pages):
+            try:
+                payload = self._json(self.service_request("GET", f"{ANALYTICS}/reports", params=params))
+                rows = parse_query_response(query, payload)
+                keys = [json.dumps(r["dimensions"], sort_keys=True) for r in rows]
+                if len(keys) != len(set(keys)) or set(keys) & seen:
+                    raise ResourceError("duplicate dimensions across pages")
+                result["rows"].extend(rows)
+                seen.update(keys)
+                result["pages"] += 1
+                if len(rows) < query.max_results:
+                    result["complete"] = True
+                    break
+                params["startIndex"] += len(rows)
+            except ResourceError as exc:
+                result["failure_reason"] = failure(exc)
+                break
+        if not result["complete"] and result["failure_reason"] is None:
+            result["failure_reason"] = "page_limit"
+        if not result["rows"]:
+            result["missing_metrics"] = {m: {"value": None, "missing_reason": result["failure_reason"] or "no_rows_or_suppressed"} for m in query.metrics}
+        days = [r["dimensions"]["day"] for r in result["rows"] if "day" in r["dimensions"]]
+        result["provenance"]["returned_date_coverage"] = {"first": min(days) if days else None, "last": max(days) if days else None,
+            "observed_days": len(set(days)), "limitation": "pagination complete does not prove all requested dates available"}
+        result["provenance"]["metric_definitions"] = {m: {"url": "https://developers.google.com/youtube/analytics/metrics#" + m,
+            "aggregation": "official returned value; no local aggregation", "unit": {"estimatedMinutesWatched": "minutes", "estimatedRedMinutesWatched": "minutes",
+                "averageViewDuration": "seconds", "averageViewPercentage": "percentage", "viewerPercentage": "percentage"}.get(m, "see exact provider metric definition")} for m in query.metrics}
+        return result
+
+    def compare(self, end_date, metrics=None, video_ids=None):
+        result = {"source": "official_period_values_side_by_side", "windows": [], "causal_claim": False,
+            "confounders": ["publication cadence", "audience mix", "paid traffic", "seasonality", "provider latency/suppression", "definition changes"],
+            "aggregation": "none; no summed rates or unweighted means"}
+        metrics = list(dict.fromkeys([*(metrics or ["views", "averageViewDuration"]), "views"]))
+        for days in (7, 28):
+            current = self.query(ReportQuery(start_date=end_date-timedelta(days=days-1), end_date=end_date, metrics=metrics, video_ids=video_ids or []))
+            prior = self.query(ReportQuery(start_date=end_date-timedelta(days=2*days-1), end_date=end_date-timedelta(days=days), metrics=metrics, video_ids=video_ids or []))
+            result["windows"].append({"days": days, "current": current, "previous": prior,
+                "sample_size": {"unit": "provider views, not unique viewers", "current": self._sample(current), "previous": self._sample(prior)}})
+        return result
+
+    @staticmethod
+    def _sample(result):
+        return result["rows"][0]["metrics"].get("views") if result["complete"] and len(result["rows"]) == 1 else {"value": None, "missing_reason": "incomplete_or_unavailable"}
+
+    def batch_stats(self, video_ids, parts=None):
+        parts = parts or ["id", "statistics"]
+        if not isinstance(video_ids, list) or not 1 <= len(video_ids) <= 50 or len(set(video_ids)) != len(video_ids) or not isinstance(parts, list) or not parts or set(parts)-{"id", "snippet", "statistics", "contentDetails"}:
+            raise ResourceError("batch requires 1..50 distinct owned IDs and documented parts (local bound)")
+        account = self.identity()
+        for vid in video_ids:
+            self.one("videos", resource_id(vid), parts="snippet")
+        payload = self._json(self.service_request("GET", f"{API}/videos:batchGetStats", params={"id": ",".join(video_ids), "part": ",".join(parts)}))
+        rows, summary = payload.get("items"), payload.get("summary")
+        has_summary = "summary" in payload
+        if not isinstance(rows, list) or has_summary and not isinstance(summary, dict):
+            raise ResourceError("batch stats invalid envelope")
+        ids = [r.get("id") if isinstance(r, dict) else None for r in rows]
+        if any(not isinstance(v, str) for v in ids) or len(set(ids)) != len(ids) or set(ids)-set(video_ids):
+            raise ResourceError("batch stats returned duplicate, missing or unexpected identity")
+        # Actual responses can omit the documented summary entirely. Returned
+        # exact IDs still establish their own values; absence of another ID does
+        # not establish provider failure. Explicit null/malformed summaries fail.
+        failed = summary.get("failedVideoIds", []) if has_summary else []
+        if has_summary and (not isinstance(failed, list) or any(not isinstance(v, str) for v in failed)
+            or len(set(ids+failed)) != len(ids+failed) or set(ids+failed) != set(video_ids)
+            or any(unsigned_long(summary.get(k)) != n for k, n in {"requestedVideoCount": len(video_ids), "succeededVideoCount": len(rows), "failedVideoCount": len(failed)}.items())):
+            raise ResourceError("batch stats exact success/failure IDs or counts mismatch")
+        unaccounted = [v for v in video_ids if v not in set(ids+failed)]
+        p = provenance("youtube.videos.batchGetStats", account)
+        p.update({"credential_observation": self.credential_observation, "provider_summary_present": has_summary,
+            "partition_provenance": "returned ID membership checked locally; missing IDs without summary have unknown provider outcomes",
+            "period": "cumulative_snapshot_not_Analytics", "definitions_url": "https://developers.google.com/youtube/v3/docs/videos#statistics.viewCount",
+            "viewCount_definition_effective": "2026-08-24", "viewCount_definition": "playback-start counting across formats per resource docs; do not apply to Analytics"})
+        outcomes = {v: {"value": None, "missing_reason": "provider_failed_id"} for v in failed}
+        outcomes.update({v: {"value": None, "missing_reason": "provider_outcome_unaccounted"} for v in unaccounted})
+        for row in rows:
+            item = {"value": row, "missing_reason": None}
+            if "statistics" in parts:
+                stats = row.get("statistics", {})
+                if not isinstance(stats, dict):
+                    raise ResourceError("batch statistics schema invalid")
+                item["statistics"] = {}
+                for name in ("viewCount", "likeCount", "commentCount"):
+                    value = stats.get(name)
+                    item["statistics"][name] = metric_value(unsigned_long(value) if value is not None else None, "provider_field_absent")
+            outcomes[row["id"]] = item
+        return {"outcomes": outcomes, "summary": summary, "complete": not unaccounted,
+            "provider_summary": {"value": summary, "missing_reason": None if has_summary else "provider_summary_omitted"},
+            "observed_partition": {"source": "local_exact_id_validation", "returned_ids": ids,
+                "provider_failed_ids": failed if has_summary else None, "unaccounted_ids": unaccounted}, "provenance": p}

socialctl/metricas/analytics_ingest.py

@@ -0,0 +1,260 @@
+"""Bounded lossless CSV parsing and crash-safe version/active-period checkpoints."""
+import csv
+from datetime import date
+import io
+import json
+import os
+from pathlib import Path
+import stat
+import tempfile
+import uuid
+from typing import Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict
+
+from socialctl.identity import credential_metadata
+from socialctl.management.resource_changes import ResourceStore, digest, save_download
+from socialctl.management.youtube_resources import ResourceError
+from socialctl.metricas.analytics_client import opaque
+from socialctl.metricas.analytics_schema import metric_value, provenance
+from socialctl.metricas.reporting_client import MAX_CSV, instant, report_period
+
+DIMENSIONS = set("date channel_id video_id playlist_id country_code province_code playback_location_type playback_location_detail live_or_on_demand subscribed_status traffic_source_type traffic_source_detail device_type operating_system age_group gender sharing_service annotation_type annotation_id card_type card_id end_screen_element_type end_screen_element_id subtitle_language subtitle_language_autotranslated".split())
+COUNTS = set("views engaged_views comments likes dislikes shares subscribers_gained subscribers_lost videos_added_to_playlists videos_removed_from_playlists card_clicks card_impressions card_teaser_clicks card_teaser_impressions annotation_clicks annotation_impressions annotation_closable_impressions annotation_clickable_impressions annotation_closes end_screen_element_clicks end_screen_element_impressions".split())
+COUNTS |= {"red_views", "video_thumbnail_impressions"}
+FLOATS = {"watch_time_minutes": "minutes", "average_view_duration_seconds": "seconds", "average_view_duration_percentage": "percentage",
+    "annotation_click_through_rate": "rate", "annotation_close_rate": "rate", "card_click_rate": "rate", "card_teaser_click_rate": "rate",
+    "end_screen_element_click_rate": "rate", "views_percentage": "percentage", "red_watch_time_minutes": "minutes", "video_thumbnail_impressions_ctr": "percentage"}
+DEFINITIONS = "https://developers.google.com/youtube/reporting/v1/reports/"
+
+
+class StudioMetadata(BaseModel):
+    """Normalize JSON strings and safe_load's native YAML date/time values."""
+    model_config = ConfigDict(extra="forbid")
+    source: Literal["youtubeStudio"]
+    account_id: str
+    export_id: str
+    start_date: date
+    end_date: date
+    exported_at: AwareDatetime
+    source_filename: str
+
+
+def read_supplied(path, maximum=MAX_CSV):
+    try:
+        fd = os.open(Path(path), os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(fd, "rb") as stream:
+            before = os.fstat(stream.fileno())
+            if not stat.S_ISREG(before.st_mode) or not 0 < before.st_size <= maximum:
+                raise ResourceError("supplied file must be bounded nonempty regular file")
+            data = stream.read(maximum+1)
+            after = os.fstat(stream.fileno())
+            if (before.st_size, before.st_mtime_ns, before.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns) or len(data) != before.st_size:
+                raise ResourceError("supplied file changed during read")
+            return data
+    except OSError:
+        raise ResourceError("cannot read supplied file without following symlinks") from None
+
+
+def parse_csv(data, binding):
+    if not isinstance(data, bytes) or not 0 < len(data) <= MAX_CSV:
+        raise ResourceError("CSV byte limit")
+    try:
+        text = data.decode("utf-8-sig")
+        if "\x00" in text:
+            raise ValueError()
+        reader = csv.reader(io.StringIO(text, newline=""), strict=True)
+        headers = next(reader)
+        if not headers or len(headers) > 256 or len(set(headers)) != len(headers) or any(not h or len(h) > 256 for h in headers):
+            raise ValueError()
+        reporting = binding["source"] == "youtubeReporting"
+        if reporting:
+            start, end = report_period(binding["report"])
+            if "date" not in headers:
+                raise ResourceError("schema: report has no date; raw download may be saved separately")
+        else:
+            start, end = date.fromisoformat(binding["start_date"]), date.fromisoformat(binding["end_date"])
+        rows, seen = [], set()
+        known = DIMENSIONS | COUNTS | set(FLOATS) if reporting else set()
+        columns = {h: {"kind": "dimension" if h in DIMENSIONS and reporting else "metric" if h in COUNTS|set(FLOATS) and reporting else "unknown",
+            "semantics_source": "official_catalog_2026-09-13" if h in known else "unknown",
+            "definition_url": DEFINITIONS + ("dimensions#" if h in DIMENSIONS else "metrics#") + h if h in known else None,
+            "unit": "count" if h in COUNTS and reporting else FLOATS.get(h) if reporting else None} for h in headers}
+        for raw in reader:
+            if len(rows) >= 100000 or len(raw) != len(headers) or any(len(v) > 8192 for v in raw):
+                raise ResourceError("CSV row/column/cell limit or schema mismatch")
+            values = dict(zip(headers, raw))
+            # Only vetted Reporting dimensions establish a row's primary key.
+            # Unknown semantics (especially Studio titles) cannot justify dedupe;
+            # preserve every such row in source order, including identical rows.
+            if reporting and set(headers) <= known:
+                identity = tuple(values[h] for h in headers if h in DIMENSIONS)
+                if identity in seen:
+                    raise ResourceError("duplicate CSV dimension identity")
+                seen.add(identity)
+            if reporting:
+                raw_date = values["date"]
+                if len(raw_date) != 8 or not raw_date.isdigit():
+                    raise ResourceError("schema: Reporting date requires YYYYMMDD")
+                day = date.fromisoformat(raw_date[:4]+"-"+raw_date[4:6]+"-"+raw_date[6:])
+                if not start <= day <= end:
+                    raise ResourceError("CSV date outside bound report")
+                if values.get("channel_id") not in {None, "", binding["account_id"]}:
+                    raise ResourceError("CSV account mismatch")
+            row = {"raw": values, "dimensions": {}, "metrics": {}, "unknown": {}}
+            for h, value in values.items():
+                if columns[h]["kind"] == "dimension":
+                    row["dimensions"][h] = value
+                elif columns[h]["kind"] == "metric":
+                    number = None if value == "" else int(value) if h in COUNTS else float(value)
+                    row["metrics"][h] = metric_value(number, "empty_csv_cell_not_zero")
+                else:
+                    row["unknown"][h] = {"raw": value, "missing_reason": "unknown_column_semantics"}
+            rows.append(row)
+        return {"headers": headers, "columns": columns, "rows": rows}
+    except (ValueError, UnicodeError, csv.Error, StopIteration):
+        raise ResourceError("CSV schema/encoding/numeric value invalid; no checkpoint committed") from None
+
+
+class ObservationStore(ResourceStore):
+    def __init__(self, brand_root, account_id):
+        self.root = Path(brand_root) / ".socialctl" / "youtube-observations"
+        self.account_id = opaque(account_id)
+
+    def _read_json(self, path):
+        value=json.loads(read_supplied(path, 128*1024*1024))
+        provenance=value.get('provenance',{})
+        if provenance and provenance.get('source')!='youtubeStudio':
+            from socialctl.youtube_data import require_fresh_api_data
+            require_fresh_api_data(provenance.get('observed_at'))
+        return value
+
+    def index(self):
+        self._ensure_root()
+        path = self.root / "index.json"
+        if not path.exists() and not path.is_symlink():
+            return {"version": 1, "account_id": self.account_id, "imports": {}, "active": {}}
+        value = self._read_json(path)
+        if value.get("version") != 1 or value.get("account_id") != self.account_id:
+            raise ResourceError("observation index account/schema mismatch")
+        return value
+
+    def _commit_index(self, value):
+        raw = json.dumps(value, ensure_ascii=False, sort_keys=True).encode()
+        if len(raw) > 16*1024*1024:
+            raise ResourceError("checkpoint size limit")
+        if (self.root / "index.json").is_symlink():
+            raise ResourceError("checkpoint symlink rejected")
+        fd, temporary = tempfile.mkstemp(dir=self.root, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "wb") as stream:
+                stream.write(raw)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, self.root / "index.json")
+            self._sync_directory(self.root)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    def _immutable_file(self, path, data):
+        if path.exists() or path.is_symlink():
+            if read_supplied(path, max(len(data), MAX_CSV)) != data:
+                raise ResourceError("immutable observation file conflict")
+        else:
+            save_download(path, data)
+
+    def import_csv(self, data, binding):
+        # Canonicalize supplied metadata before checking ownership or persistence.
+        if binding.get("source") == "youtubeStudio":
+            binding = StudioMetadata.model_validate(binding).model_dump(mode="json")
+        binding = json.loads(json.dumps(binding, allow_nan=False))
+        # This observation describes authorization at read time, not the report's
+        # immutable identity. A changed grant/expiry must not defeat report dedupe.
+        credentials = binding.pop("credential_observation", None)
+        if binding.get("account_id") != self.account_id:
+            raise ResourceError("import account mismatch")
+        source = binding.get("source")
+        if source == "youtubeReporting":
+            report = binding.get("report", {})
+            rid, job, rtype = opaque(report.get("id")), opaque(binding.get("job_id")), opaque(binding.get("report_type_id"))
+            if report.get("jobId") != job:
+                raise ResourceError("report/job binding mismatch")
+            start, end = report_period(report)
+            created = instant(report.get("createTime")).isoformat()
+            period = [source, self.account_id, job, rtype, start.isoformat(), end.isoformat()]
+            identifier = [source, self.account_id, job, rid]
+        elif source == "youtubeStudio":
+            rid = opaque(binding.get("export_id"))
+            start, end = date.fromisoformat(binding["start_date"]), date.fromisoformat(binding["end_date"])
+            if start > end:
+                raise ResourceError("invalid supplied export dates")
+            created = instant(binding.get("exported_at")).isoformat()
+            if not isinstance(binding.get("source_filename"), str) or not binding["source_filename"]:
+                raise ResourceError("supplied source filename required")
+            period = [source, self.account_id, rid, start.isoformat(), end.isoformat()]
+            identifier = [source, self.account_id, rid]
+        else:
+            raise ResourceError("unsupported CSV provenance source")
+        parsed = parse_csv(data, binding)
+        key = digest(json.dumps(identifier).encode())
+        period_key = digest(json.dumps(period).encode())
+        checksum = digest(data)
+        binding_digest = digest(json.dumps(binding, sort_keys=True).encode())
+        with self.apply_lock(str(uuid.uuid5(uuid.NAMESPACE_URL, "youtube-observations-index"))):
+            index = self.index()
+            existing = index["imports"].get(key)
+            if existing:
+                if (existing["sha256"], existing["binding_sha256"]) != (checksum, binding_digest):
+                    raise ResourceError("same report ID has different bytes/binding; refuses overwrite")
+                return self._read_json(self.root / (key + ".json"))
+            p = provenance(source, self.account_id)
+            p.update({"account_binding": "authenticated_report_job_chain" if source == "youtubeReporting" else "user_supplied_not_API_verified",
+                "definitions_url": DEFINITIONS + "metrics" if source == "youtubeReporting" else None,
+                "dimensions": [h for h in parsed["headers"] if parsed["columns"][h]["kind"] == "dimension"],
+                "latency": "first report up to 48h; generated files only" if source == "youtubeReporting" else "user_supplied_export",
+                "historical_coverage": "provider generated; normal downloads 60 days, historical 30 days; not promised lifetime" if source == "youtubeReporting" else "declared supplied period"})
+            if source == "youtubeReporting":
+                p["credential_observation"] = credentials if credentials is not None else credential_metadata({})
+            if source == "youtubeStudio":
+                p["retention"] = {"category": "user_supplied_export", "api_cleanup_eligible": False,
+                    "originals": "supplied original files are never changed or removed"}
+            observation = {"id": key, "binding": binding, "sha256": checksum, "provenance": p, **parsed}
+            serialized = json.dumps(observation, ensure_ascii=False, allow_nan=False).encode()
+            if len(serialized) > 128*1024*1024:
+                raise ResourceError("parsed observation byte limit; no checkpoint committed")
+            # A crash can leave orphan immutable files, but only the final atomic
+            # index replacement activates a complete import. Recovery reuses bytes.
+            raw_path = self.root / (key + ".csv")
+            parsed_path = self.root / (key + ".json")
+            self._immutable_file(raw_path, data)
+            if parsed_path.exists():
+                orphan = self._read_json(parsed_path)
+                if orphan.get("sha256") != checksum or orphan.get("binding") != binding:
+                    raise ResourceError("orphan import binding conflict")
+                observation = orphan
+            else:
+                self._immutable_file(parsed_path, serialized)
+            index["imports"][key] = {"sha256": checksum, "binding_sha256": binding_digest, "period_key": period_key, "created_at": created, "checkpoint": "complete"}
+            previous = index["active"].get(period_key)
+            if previous is None or created > index["imports"][previous]["created_at"]:
+                index["active"][period_key] = key
+            elif created == index["imports"][previous]["created_at"]:
+                raise ResourceError("ambiguous equal-time backfill; no active version guessed")
+            self._commit_index(index)
+            return observation
+
+    def save_query(self, result):
+        if result.get("provenance", {}).get("account_id") != self.account_id:
+            raise ResourceError("query account mismatch")
+        self._ensure_root()
+        data = json.dumps(result, ensure_ascii=False, allow_nan=False).encode()
+        if len(data) > 128*1024*1024:
+            raise ResourceError("query observation byte limit")
+        key = digest(data)
+        self._immutable_file(self.root / (key + ".query.json"), data)
+        return {"id": key, "path": str(self.root / (key + ".query.json")), "complete": result["complete"]}
+
+    def active(self):
+        index = self.index()
+        return [self._read_json(self.root / (key + ".json")) for key in index["active"].values()]