pushframe 5.0.0__py3-none-any.whl

pushframe/google/cache.py

@@ -0,0 +1,167 @@
+"""Pruned-disk download cache for Google album items (phase 18 plan 18-01).
+
+The cache is a STAGING area only — `cache_dir/<google_media_id>` files hold
+the exact `=d` bytes (never re-encoded; LGS-06: the bytes decide) while they
+wait for their confirmed frame upload, and are pruned afterwards (CSE-04).
+Nothing in the pipeline ever diffs by walking it — demand is rebuilt from the
+album listing plus the manifest (CSE-03, plan 18-02 builds that side).
+
+SAFE-04 discipline: a download that fails (HTTP error, transport error, or a
+Content-Length/expected-size mismatch) is recorded in CacheOutcome.failed and
+its bytes are NEVER written, NEVER hashed — a failed or partial download can
+never become uploadable junk bytes.
+
+Concurrency is confined to this module (D-06 / CSE-01): a bounded worker pool
+over the GoogleSession's httpx client. It imports nothing from the sync/apply
+side of the project and never touches an Aura client, so concurrent code
+structurally cannot reach the frame-write seam.
+"""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pushframe.aws.s3client import get_md5
+
+
+class CacheError(RuntimeError):
+    """Cache staging failed in a way that must abort the sync run."""
+
+
+@dataclass
+class CacheOutcome:
+    """The result of one download_to_cache run over an album listing.
+
+    staged entries carry {"google_media_id", "path", "md5_hash",
+    "size_bytes"} — verified, hash-annotated files ready for upload planning.
+    `failed` carries (google_media_id, error) pairs; those ids are excluded
+    from any plan (SAFE-04) and reported, never silently dropped.
+    """
+
+    staged: list[dict] = field(default_factory=list)
+    failed: list[tuple[str, str]] = field(default_factory=list)
+    skipped_manifest: int = 0
+    videos_skipped: int | None = None
+
+    @property
+    def staged_by_id(self) -> dict[str, dict]:
+        return {s["google_media_id"]: s for s in self.staged}
+
+
+def _download_one(session, item: dict, cache_dir: Path,
+                  expected_size: int | None) -> dict:
+    """Fetch ONE item's `=d` bytes, verify length, write, hash.
+
+    Raises on any failure — the caller records it in CacheOutcome.failed and
+    guarantees no file was left behind for the failed id.
+    """
+    google_media_id = item["id"]
+    resp = session.http.get(f"{item['base_url']}=d")
+    if resp.status_code != 200:
+        raise RuntimeError(f"=d download returned HTTP {resp.status_code}")
+    body = resp.content
+    declared = resp.headers.get("content-length")
+    # A stream transport may not populate Content-Length even for complete
+    # bodies; when the header is absent, the expected_size (phase 16's
+    # Range-GET measurement) is the length check.
+    if declared is not None and int(declared) != len(body):
+        raise RuntimeError(
+            f"truncated download: Content-Length {declared} != received {len(body)}"
+        )
+    if declared is None and expected_size is not None and expected_size != len(body):
+        raise RuntimeError(
+            f"truncated download: expected {expected_size} != received {len(body)}"
+        )
+    path = cache_dir / google_media_id
+    path.write_bytes(body)
+    return {
+        "google_media_id": google_media_id,
+        "path": str(path),
+        "md5_hash": get_md5(body),
+        "size_bytes": len(body),
+    }
+
+
+def download_to_cache(session, listing, cache_dir: Path, *,
+                      expected_sizes: dict[str, int] | None = None,
+                      manifest=None, workers: int = 4,
+                      progress=None) -> CacheOutcome:
+    """Download every listing item that the manifest does not already cover.
+
+    Manifest members are skipped entirely (D-07): steady state = zero
+    downloads, zero cache residency — their md5 lives in the manifest and the
+    frame already holds the bytes. Concurrency is a bounded pool (default 4,
+    injectable down to 1); results are merged after shutdown, so no shared
+    mutable state is touched during flight. `progress(google_media_id, ok)`
+    is invoked per RESOLVED item (success or failure) after the merge, so a
+    CLI can drive a progress bar (CSE-08) without thread races.
+    """
+    cache_dir = Path(cache_dir)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    expected_sizes = expected_sizes or {}
+    outcome = CacheOutcome()
+
+    todo: list[dict] = []
+    for item in listing.items:
+        if manifest is not None and manifest.entry_for(item["id"]) is not None:
+            outcome.skipped_manifest += 1
+        else:
+            todo.append(item)
+
+    if todo:
+        with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+            futures = {
+                pool.submit(_download_one, session, item, cache_dir,
+                            expected_sizes.get(item["id"])): item["id"]
+                for item in todo
+            }
+            for fut, google_media_id in futures.items():
+                try:
+                    outcome.staged.append(fut.result())
+                except Exception as exc:  # per-item isolation: one bad download
+                    outcome.failed.append((google_media_id, str(exc)))
+        # A crash or transport error mid-write could strand a partial file;
+        # a failed id must leave NOTHING staged-looking behind (SAFE-04).
+        staged_ids = {s["google_media_id"] for s in outcome.staged}
+        for google_media_id, _err in outcome.failed:
+            orphan = cache_dir / google_media_id
+            if google_media_id not in staged_ids and orphan.exists():
+                orphan.unlink()
+
+    if progress is not None:
+        for s in outcome.staged:
+            progress(s["google_media_id"], True)
+        for google_media_id, _err in outcome.failed:
+            progress(google_media_id, False)
+
+    return outcome
+
+
+def prune_cache(cache_dir: Path, manifest_ids: set[str]) -> int:
+    """Delete staged files whose google_media_id is manifest-backed (CSE-04).
+
+    Targeted deletions BY NAME — never a directory walk (CSE-03 discipline
+    applies to the whole module, pruning included). Files of un-manifested
+    ids (failed downloads awaiting retry) are untouched. An already-missing
+    file counts as pruned: pruning is idempotent and never raises.
+    """
+    cache_dir = Path(cache_dir)
+    if not manifest_ids:
+        return 0
+    pruned = 0
+    for google_media_id in manifest_ids:
+        f = cache_dir / google_media_id
+        if f.exists():
+            f.unlink()
+        pruned += 1
+    return pruned
+
+
+def videos_skipped(listing, metadata_item_count: int | None) -> int | None:
+    """Named video count via the live-proven metadata delta (CSE-07 / D-10):
+    album metadata item count minus the photo count the walker enumerates.
+    Returns None when the metadata count is unknown (no delta to report)."""
+    if metadata_item_count is None:
+        return None
+    return metadata_item_count - len(listing.items)

pushframe/google/client.py

@@ -0,0 +1,140 @@
+"""Google session client: full-cookie-jar httpx over photos.google.com.
+
+Migrated from probes/browser_bootstrap.py's live-proven session builder
+(phase 16). Two live-proven requirements drive the shape:
+
+1. photos.google.com treats a FLATTENED name→value cookie dict as an
+   anonymous visitor (redirect to the marketing page), while the complete
+   jar — domain+path preserved from the harvest — yields the logged-in app
+   page with the SNlM0e at-token. The jar is therefore built from the
+   vault's FULL records, never from `cookies_for_httpx()`.
+2. The User-Agent must match the harvesting browser's (Chrome); a
+   mismatched UA gets redirected to `about/`.
+
+The `transport=` seam mirrors `pushframe.client.Client`'s DI: offline tests
+inject an httpx.MockTransport and never touch the network (TEST-02).
+
+NOTE: the vault denylist refuses `pushframe.cli` — the CLI reaches the
+session only through this package's `GoogleSession.from_vault`, which is the
+boundary's intended enforcement point.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+
+import httpx
+
+from pushframe.google import vault
+
+PHOTOS_HOME = "https://photos.google.com/"
+
+# UA of the harvesting browser (live-proven: required, else redirect to about/).
+HARVEST_UA = ("Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+              "(KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36")
+
+_AUTH_COOKIE_NAMES = ("SAPISID", "__Secure-1PAPISID", "__Secure-3PAPISID")
+
+# Account email on the logged-in home page: the "oPEP7c" key with the
+# account address as value (whitespace-tolerant on the JSON separator).
+_EMAIL_RE = re.compile(r'"oPEP7c"\s*[,:]\s*"([^"@]+@[^"]+)"')
+
+# The SNlM0e at-token (XSRF boilerplate batchexecute needs).
+_SNLMOE_RE = re.compile(r'"SNlM0e"\s*:\s*"([^"]+)"')
+
+
+class GoogleSessionError(RuntimeError):
+    """Session-level failure: vault unusable or a page fetch failing loud."""
+
+
+class GoogleSession:
+    """An httpx session over photos.google.com built from the full cookie jar.
+
+    Exposes `transport=` for offline tests (httpx.MockTransport), the
+    session-usable check (`is_linked`), the SNlM0e at-token extraction, and
+    the account email (for `status` — email only, never cookie values, D-02).
+    """
+
+    def __init__(self, cookie_records: list[dict], *, transport: httpx.BaseTransport | None = None,
+                 user_agent: str = HARVEST_UA, timeout: float = 30.0) -> None:
+        self.cookie_records = cookie_records
+        self._sapisid: str | None = next(
+            (c["value"] for c in cookie_records if c.get("name") in _AUTH_COOKIE_NAMES), None)
+        # FULL jar: domain+path preserved (live-proven requirement — a
+        # flattened dict reads as anonymous).
+        jar = httpx.Cookies()
+        for c in cookie_records:
+            if "name" in c and "value" in c:
+                jar.set(c["name"], c["value"],
+                        domain=c.get("domain", ".google.com"), path=c.get("path", "/"))
+        self.http = httpx.Client(
+            cookies=jar,
+            timeout=timeout,
+            follow_redirects=True,
+            transport=transport,
+            headers={"User-Agent": user_agent,
+                     "Accept-Language": "fr-FR,fr;q=0.9,en;q=0.8"},
+        )
+        self._home_text: str | None = None
+
+    @classmethod
+    def from_vault(cls, *, path: str | None = None,
+                   **kwargs) -> "GoogleSession":
+        """Build a session from the cookie vault (denylist check fires inside
+        vault.load()). Falls back to the legacy probe vault path (soft migration).
+        """
+        return cls(vault.load(path=path), **kwargs)
+
+    @property
+    def sapisid(self) -> str | None:
+        """SAPISID value from the harvest, for SAPISIDHASH Authorization."""
+        return self._sapisid
+
+    def home_text(self) -> str:
+        """The logged-in photos home page text (fetched once, then cached)."""
+        if self._home_text is None:
+            resp = self.http.get(PHOTOS_HOME)
+            if resp.status_code != 200:
+                raise GoogleSessionError(
+                    f"photos.google.com home returned HTTP {resp.status_code} "
+                    f"with session cookies attached — failing loud"
+                )
+            self._home_text = resp.text
+        return self._home_text
+
+    def is_linked(self) -> bool:
+        """Session-usable check (no exception on a dead session).
+
+        Linked iff the photos home answers 200 with the SNlM0e at-token. A
+        dead/expired session gets redirected to the marketing page (no
+        at-token) — the live-proven anonymous signal.
+        """
+        try:
+            m = _SNLMOE_RE.search(self.home_text())
+        except GoogleSessionError:
+            return False
+        return m is not None
+
+    def at_token(self) -> str | None:
+        """The SNlM0e at-token (XSRF boilerplate for batchexecute calls)."""
+        m = _SNLMOE_RE.search(self.home_text())
+        return m.group(1) if m else None
+
+    def account_email(self) -> str | None:
+        """The linked account's email address (for `status`; D-02: email only,
+        never cookie values). None when the page shape carries no email row."""
+        m = _EMAIL_RE.search(self.home_text())
+        return m.group(1) if m else None
+
+    def authorization_header(self, origin: str = "https://photos.google.com") -> str | None:
+        """SAPISIDHASH Authorization value, or None when no SAPISID cookie —
+        some batchexecute calls expect it (xob0t/Google-Photos-Toolkit shape)."""
+        if not self._sapisid:
+            return None
+        now_ms = int(time.time() * 1000)
+        digest = hashlib.sha1(f"{now_ms} {self._sapisid} {origin}".encode()).hexdigest()
+        return f"SAPISIDHASH {now_ms}_{digest}"
+
+    def close(self) -> None:
+        self.http.close()

pushframe/google/enumerate.py

@@ -0,0 +1,270 @@
+"""Album enumeration and disk-weight measurement over photos.google.com.
+
+RPC-FIRST protocol (live-proven 2026-09-28, this session — supersedes the
+phase-16 share-page bootstrap for the linked flow):
+
+- Batch-1 IS a snAcKc call with a NULL continuation:
+  `snAcKc(album_id, null, null, page_key)` answers HTTP 200 with the first
+  300 items — the share page is never fetched. (The authenticated share
+  page is an SPA shell: no ds:1 block, no AH_ cursor — the phase-16
+  share-page batch-1 only ever worked for the ANONYMOUS flow.)
+- `page_key` (4th argument) is OPTIONAL: a null page_key still answers
+  (300 items on the live 1096-item album). The /albums listing carries it,
+  so it is sent when known.
+- Continuation: the LAST AH_ token in each payload is the cursor; no token
+  = exhausted. Live proof: 300+300+300+194 = 1094, clean exhaustion.
+- The album's item-count METADATA (the /albums ds:5 value) can exceed the
+  photo count the walker returns (live: 1096 metadata vs 1094 photos — the
+  delta matches the album's videos, which the §1b photo walker skips).
+  The authoritative photo count is the enumeration's.- scalars (SNlM0e at-token, FdrFJe f.sid, cfb2h bl) come from the logged-in
+photos home page; the f.req envelope is TRIPLE-nested (double nesting
+answers HTTP 400 — the phase-16 finding that started this all).
+- ONE bounded retry (post-phase-17 hardening, live smoke 2026-09-28):
+Google occasionally answers HTTP 200 with a well-formed wrb.fr/snAcKc
+entry whose inner payload is null. The exact call is re-issued once
+(same cursor — a null answer consumed no page); a null again fails
+loud. The budget is one retry per enumeration, not per page.
+
+Fail-loud discipline (T-17-02): HTTP != 200, a malformed envelope, a
+persisting null payload or a page-cap overrun raises — never a silent
+partial listing.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from urllib.parse import quote
+
+import httpx
+
+from pushframe.google.parsers import (
+    ProbeParseError,
+    parse_batchexecute,
+    parse_snackc_payload,
+)
+from pushframe.google.redaction import redact_tokens
+
+BATCHEXECUTE_URL = "https://photos.google.com/_/PhotosUi/data/batchexecute"
+PHOTOS_HOME = "https://photos.google.com/"
+PHOTOS_ALBUMS = "https://photos.google.com/albums"
+
+MAX_PAGES = 60  # 60 x 300 = 18000, far beyond any real album (T-17-04 cap)
+PAGE_SIZE = 300  # live-proven page size
+
+# ONE bounded retry for the live-observed transient (2026-09-28 smoke):
+# HTTP 200 carrying a well-formed snAcKc entry whose inner payload is
+# null. The budget is GLOBAL to one enumerate_album run — one recovery
+# per enumeration, not per page — and a null answer never consumed a
+# page, so the retry re-issues the exact same call (same cursor).
+_retry_budget = {"snAcKc_null_payload": 1}
+
+# WIZ_global_data scalars on the home page.
+_FSID_RE = _FSID_RE = None  # replaced below (kept name stable for tests)
+_FSID_RE = __import__("re").compile(r'"FdrFJe"\s*:\s*"([^"]+)"')
+_BL_RE = __import__("re").compile(r'"cfb2h"\s*:\s*"([^"]+)"')
+_AT_RE = __import__("re").compile(r'"SNlM0e"\s*:\s*"([^"]+)"')
+
+
+class EnumerateError(RuntimeError):
+    """Album enumeration failed — fail loud, never a silent partial listing."""
+
+
+@dataclass
+class AlbumListing:
+    """The complete, exhausted album listing (D-06: every item, disk weight
+    via measure_disk_weight, photo count cross-checkable against the UI)."""
+
+    items: list[dict] = field(default_factory=list)
+    page_count: int = 0
+    exhausted_cleanly: bool = False
+    album_id: str | None = None
+
+    @property
+    def total_bytes(self) -> int:
+        return sum(i.get("bytes", 0) for i in self.items)
+
+
+@dataclass
+class _SessionScalars:
+    at: str
+    fsid: str
+    bl: str
+
+
+def _session_scalars(session) -> _SessionScalars:
+    """Extract at-token / f.sid / bl from the logged-in photos home page."""
+    text = session.home_text()
+    at_m = _AT_RE.search(text)
+    fsid_m = _FSID_RE.search(text)
+    bl_m = _BL_RE.search(text)
+    if not (at_m and fsid_m and bl_m):
+        missing = [n for n, m in (("SNlM0e", at_m), ("FdrFJe", fsid_m),
+                                  ("cfb2h", bl_m)) if not m]
+        raise EnumerateError(
+            f"photos.google.com home lacks required batchexecute scalars: "
+            f"{missing} — session dead or page shape changed; failing loud"
+        )
+    return _SessionScalars(at=at_m.group(1), fsid=fsid_m.group(1), bl=bl_m.group(1))
+
+
+def _freq_envelope(rpcid: str, args: list) -> str:
+    """The TRIPLE-nested compact f.req envelope (live-proven: double nesting
+    answers HTTP 400). Shape: [[ [rpcid, <stringified args>, null, "generic"] ]] —
+    the 4-element entry sits at the third nesting level, its 2nd member being
+    the JSON-encoded args STRING."""
+    entry = [rpcid, json.dumps(args, separators=(",", ":")), None, "generic"]
+    return json.dumps([[entry]], separators=(",", ":"))
+
+
+def _rpc_headers(session) -> dict[str, str]:
+    headers = {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "Origin": PHOTOS_HOME.rstrip("/"),
+        "Referer": PHOTOS_HOME,
+    }
+    auth = session.authorization_header()
+    if auth:
+        headers["Authorization"] = auth
+    return headers
+
+
+def _snackc_page(session, scalars: _SessionScalars, album_id: str,
+                 page_key: str | None,
+                 continuation_token: str | None) -> tuple[list[dict], str | None]:
+    """Issue ONE snAcKc batchexecute call; return (items, next_token_or_None).
+
+    continuation_token=None is the live-proven batch-1 form. A null inner
+    payload on HTTP 200 (live-observed transient) is retried exactly once
+    with the same cursor while the global budget lasts; a persisting null
+    fails loud rather than emitting a partial listing."""
+    args = [album_id, continuation_token, None, page_key]
+    freq = _freq_envelope("snAcKc", args)
+    url = (
+        f"{BATCHEXECUTE_URL}?rpcids=snAcKc"
+        f"&source-path={quote('/share/' + album_id, safe='')}"
+        f"&f.sid={quote(scalars.fsid, safe='')}"
+        f"&bl={quote(scalars.bl, safe='')}"
+        f"&hl=fr&soc-app=165&soc-platform=1&soc-device=1"
+    )
+    body = f"f.req={quote(freq, safe='')}&at={quote(scalars.at, safe='')}&"
+    headers = _rpc_headers(session)
+
+    def _post() -> httpx.Response:
+        return session.http.post(url, content=body.encode("utf-8"),
+                                 headers=headers)
+
+    def _snackc_entries(resp: httpx.Response) -> list:
+        if resp.status_code != 200:
+            raise EnumerateError(
+                f"snAcKc batchexecute returned HTTP {resp.status_code} "
+                f"(album {album_id[:12]}…, continuation sent: "
+                f"{continuation_token is not None}) — failing loud; body head: "
+                f"{redact_tokens(resp.text[:200])}"
+            )
+        entries = [e for e in parse_batchexecute(resp.text)
+                   if e.rpcid == "snAcKc"]
+        if not entries:
+            raise EnumerateError(
+                "snAcKc batchexecute answer carries no wrb.fr/snAcKc entry — "
+                "malformed envelope; refusing to guess"
+            )
+        return entries
+
+    entries = _snackc_entries(_post())
+    if entries[0].payload is None and _retry_budget["snAcKc_null_payload"] > 0:
+        _retry_budget["snAcKc_null_payload"] -= 1
+        entries = _snackc_entries(_post())
+    if entries[0].payload is None:
+        raise EnumerateError(
+            "snAcKc carries a null inner payload on HTTP 200 (live-observed "
+            "transient); the single bounded retry did not recover it — "
+            "failing loud, never a partial listing"
+        )
+    page = parse_snackc_payload(entries[0].payload)
+    return page.items, page.continuation_token
+
+
+def enumerate_album(session, album_id: str, *, page_key: str | None = None,
+                    max_pages: int = MAX_PAGES) -> AlbumListing:
+    """Enumerate EVERY photo of an album (D-06) via the RPC-first protocol:
+
+    batch-1 = snAcKc(album_id, None, None, page_key) → 300 items; swap the
+    LAST AH_ cursor per page until no token or a 0-item page. Fail-loud on
+    HTTP != 200 or a malformed envelope (never a silent partial listing).
+
+    `album_id` is the SHARE token (the /share/<id> path segment — what the
+    /albums listing carries and what the live proof used). `page_key` is
+    the share URL's ?key= value when known (optional, live-proven).
+
+    A null-payload snAcKc answer on HTTP 200 (live-observed transient) is
+    retried once per run with the same cursor — see _snackc_page.
+    """
+    if not album_id or not isinstance(album_id, str):
+        raise EnumerateError("album_id is required — refusing to guess")
+    _retry_budget["snAcKc_null_payload"] = 1  # one bounded retry per run
+    scalars = _session_scalars(session)
+
+    listing = AlbumListing(album_id=album_id)
+    token: str | None = None
+    while listing.page_count < max_pages:
+        page_items, next_token = _snackc_page(session, scalars, album_id,
+                                              page_key, token)
+        listing.page_count += 1
+        known = {i["id"] for i in listing.items}
+        fresh = [i for i in page_items if i["id"] not in known]
+        listing.items.extend(fresh)
+        if next_token is None or not page_items:
+            listing.exhausted_cleanly = True
+            return listing
+        token = next_token
+
+    raise EnumerateError(
+        f"album enumeration hit the {max_pages}-page cap (T-17-04) with "
+        f"{len(listing.items)} items and a live continuation token — "
+        f"listing is INCOMPLETE; raise max_pages or investigate"
+    )
+
+
+def list_shared_albums(session) -> list:
+    """The account's shared albums, from photos.google.com/albums' ds:5 block
+    (live-proven: 3 albums with titles, share tokens, base64 page_keys and
+    metadata item counts; the 'Cadre' row's count = 24 matched the UI).
+
+    Note: the home page's ds:5 is the photo feed — the /albums page is the
+    one that carries the album cards.
+    """
+    from pushframe.google.parsers import extract_initdata, parse_album_summaries
+
+    resp = session.http.get(PHOTOS_ALBUMS)
+    if resp.status_code != 200:
+        raise EnumerateError(
+            f"photos.google.com/albums returned HTTP {resp.status_code} "
+            f"— failing loud"
+        )
+    try:
+        ds5 = extract_initdata(resp.text, "ds:5")
+    except ProbeParseError:
+        # An account with no albums renders a ds:5 without card rows — a
+        # legitimate empty listing, not a parse failure.
+        return []
+    return parse_album_summaries(ds5)
+
+
+def measure_disk_weight(session, base_urls: list[str]) -> list[int]:
+    """Exact per-item byte sizes via 1-octet Range GETs on `{baseUrl}=d`.
+
+    Google answers `Content-Range: bytes 0-0/TOTAL` — the album's total disk
+    weight is measurable without downloading any photo (live-proven: album C,
+    24 items → 86.6 MiB exact). Items whose answer carries neither
+    Content-Range nor Content-Length report 0 (defensive; live never seen).
+    """
+    sizes: list[int] = []
+    for base in base_urls:
+        r = session.http.get(f"{base}=d", headers={"Range": "bytes=0-0"})
+        cr = r.headers.get("content-range", "")
+        size = int(cr.rsplit("/", 1)[-1]) if "/" in cr else None
+        if size is None:
+            cl = r.headers.get("content-length")
+            size = int(cl) if cl else 0
+        sizes.append(size)
+    return sizes

pushframe/google/manifest.py

@@ -0,0 +1,111 @@
+"""Persistent google_media_id → md5_hash manifest (phase 18 plan 18-01).
+
+This file is the sole memory that survives cache pruning: a manifest entry
+MEANS "this photo lives on the frame" (its md5_hash was confirmed uploaded).
+The mirror plan is rebuilt from the album listing plus THIS file — never from
+a directory walk of the (pruned) cache (CSE-02/CSE-03).
+
+Privacy posture: ids, hashes and sizes only — no cookie material, no
+capability URLs. The cookie vault's structural denylist is therefore not
+implicated by this module, but the vault's FILE discipline is mirrored:
+0600 permissions and an atomic temp+rename write so a crash mid-save can
+never leave a truncated manifest behind.
+
+Entry shape is closed (fail loud on anything else):
+
+    {"md5_hash": str, "size_bytes": int,
+     "album_share_token": str, "first_synced": iso8601}
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+DEFAULT_MANIFEST_PATH = Path("~/.config/pushframe/google-manifest.json")
+
+# The ONLY keys a manifest entry may carry. Anything else fails loud on load —
+# this file must never become a bag of unvetted per-id state (and can never
+# accumulate secrets without tripping this guard).
+_ENTRY_KEYS = frozenset(
+    {"md5_hash", "size_bytes", "album_share_token", "first_synced"}
+)
+
+
+class ManifestError(RuntimeError):
+    """Manifest absent-malformed, or an entry violating the closed shape."""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _validate_entry(google_media_id: str, entry: object) -> dict:
+    if not isinstance(entry, dict):
+        raise ManifestError(
+            f"manifest entry for {google_media_id!r} is not an object — "
+            f"refusing to guess"
+        )
+    keys = set(entry)
+    if keys != set(_ENTRY_KEYS):
+        unexpected = keys - _ENTRY_KEYS
+        missing = _ENTRY_KEYS - keys
+        raise ManifestError(
+            f"manifest entry for {google_media_id!r} violates the closed "
+            f"shape — unexpected keys: {sorted(unexpected)}, "
+            f"missing: {sorted(missing)}"
+        )
+    if not isinstance(entry["md5_hash"], str) or not entry["md5_hash"]:
+        raise ManifestError(f"entry {google_media_id!r}: md5_hash must be a non-empty string")
+    if not isinstance(entry["size_bytes"], int) or isinstance(entry["size_bytes"], bool):
+        raise ManifestError(f"entry {google_media_id!r}: size_bytes must be an int")
+    return entry
+
+
+@dataclass
+class GoogleManifest:
+    """The in-memory manifest map with load/save and entry access."""
+
+    entries: dict[str, dict] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> "GoogleManifest":
+        """Read the manifest; an ABSENT file is a legitimate empty manifest
+        (first run), while a present-but-malformed one fails loud."""
+        p = Path(path).expanduser() if path else DEFAULT_MANIFEST_PATH.expanduser()
+        if not p.exists():
+            return cls()
+        data = json.loads(p.read_text())
+        if not isinstance(data, dict):
+            raise ManifestError(f"manifest at {p} is not a JSON object — refusing to guess")
+        return cls(entries={mid: _validate_entry(mid, e) for mid, e in data.items()})
+
+    def entry_for(self, google_media_id: str) -> dict | None:
+        return self.entries.get(google_media_id)
+
+    def add(self, google_media_id: str, *, md5_hash: str, size_bytes: int,
+            album_share_token: str, first_synced: str | None = None) -> None:
+        self.entries[google_media_id] = {
+            "md5_hash": md5_hash,
+            "size_bytes": size_bytes,
+            "album_share_token": album_share_token,
+            "first_synced": first_synced or _now_iso(),
+        }
+
+    def save(self, path: str | Path | None = None) -> Path:
+        """Persist atomically (temp file + os.replace) with 0600 permissions —
+        a crash mid-save can never leave a truncated manifest behind."""
+        p = Path(path).expanduser() if path else DEFAULT_MANIFEST_PATH.expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(self.entries, indent=2, sort_keys=True).encode("utf-8")
+        tmp = p.with_name(p.name + ".tmp")
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, payload)
+        finally:
+            os.close(fd)
+        os.replace(tmp, p)
+        os.chmod(p, 0o600)  # in case the file pre-existed with looser mode
+        return p