socialcli 0.3.0__py3-none-any.whl

socialctl/media_preflight.py

@@ -0,0 +1,114 @@
+"""Local diagnostics across ordinary publication routes, preserving partial results."""
+from pathlib import Path
+
+from socialctl.adapters import ADAPTADORES
+from socialctl.media import leer_media,MediaNoEncontrada,MediaInvalida
+from socialctl.media_requirements import SOURCES,technical_issues
+from socialctl.models import MediaAsset,MediaKind,Platform
+from socialctl.postfile import _ruta,_cargar_datos,_construir_platform_post,_validar_nombre_de_media,PostInvalido
+from socialctl.publication_policy import validate_derivation
+from socialctl.read_reports import safe_error
+
+
+def issue(code,message,*,field='media',action='supply_compatible_media'):
+    return {'code':code,'field':field,'action':action,'retryable':False,'message':safe_error(message)}
+
+
+def check_post(brand,slug,only=()):
+    path=_ruta(brand,slug)
+    raw=_cargar_datos(path)
+    blocks=raw.get('platforms')
+    if not isinstance(blocks,dict) or not blocks:raise PostInvalido('post requires platform mappings')
+    try:available={Platform(p) for p in blocks}
+    except ValueError:raise PostInvalido('unknown platform in post') from None
+    selected=set(only) if only else available
+    if not selected<=available:raise PostInvalido('selected platform absent from post')
+    cache={};platforms={}
+    for platform in sorted(selected,key=lambda p:p.value):
+        diagnostics=[];assets=[]
+        def read(file,*,ruta_relativa):
+            key=str(file.resolve())
+            if key not in cache:
+                try:
+                    asset=leer_media(file,ruta_relativa=ruta_relativa)
+                    cache[key]=(asset,None)
+                except (MediaNoEncontrada,FileNotFoundError):
+                    cache[key]=(None,issue('media_missing','Supplied file is missing.'))
+                except MediaInvalida as exc:
+                    action='install_probe' if exc.code=='probe_unavailable' else 'inspect_file' if exc.code=='probe_timeout' else 'supply_compatible_media'
+                    cache[key]=(None,issue(exc.code,'Local media inspection did not produce usable metadata.',action=action))
+                except (OSError,ValueError,TypeError):
+                    cache[key]=(None,issue('media_unreadable','Supplied file could not be inspected.'))
+            asset,error=cache[key]
+            record={'file':safe_error(ruta_relativa),'status':'blocked' if error else 'inspected'}
+            if error:
+                diagnostics.append({**error,'file':safe_error(ruta_relativa)})
+                record['issue']=error
+                asset=MediaAsset(path=file,kind=MediaKind.VIDEO,ruta_relativa=ruta_relativa)
+            else:
+                record['metadata']={'kind':asset.kind.value,'width':asset.width,'height':asset.height,
+                    'duration_s':asset.duration_s,'size_bytes':asset.size_bytes,'technical':asset.probe}
+            assets.append(record)
+            return asset
+        block=blocks[platform.value]
+        prepared={}
+        # Inspect each path independently, even when other post fields are invalid.
+        if isinstance(block,dict) and isinstance(block.get('media',[]),list):
+            safe_names=[]
+            for index,name in enumerate(block.get('media',[])):
+                try:
+                    file=_validar_nombre_de_media(brand.raiz/'media',name)
+                    relative=file.relative_to(brand.raiz/'media').as_posix()
+                except (ValueError,TypeError,OSError):
+                    error=issue('media_path_invalid','Supply a relative file path inside the brand media directory.')
+                    label=safe_error(name) if isinstance(name,str) else f'entry {index+1}'
+                    assets.append({'file':label,'status':'blocked','issue':error})
+                    diagnostics.append({**error,'file':label})
+                    continue
+                prepared[str(file)]=read(file,ruta_relativa=relative)
+                safe_names.append(name)
+            block={**block,'media':safe_names}
+        try:
+            post=_construir_platform_post(platform,block,brand.raiz/'media',path,
+                media_reader=lambda file,**kwargs:prepared[str(file)])
+            errors=ADAPTADORES[platform]().validate(post,brand)+validate_derivation(post,require_origin=True)
+            detailed=[i for asset in post.media for i in technical_issues(platform,asset)]
+            detailed_messages={i['message'] for i in detailed}
+            diagnostics.extend({**i,'field':'media'} for i in detailed)
+            for error in errors:
+                if error.motivo in detailed_messages:continue
+                action=('configure_account' if error.campo in {'cuenta','auditoria','credenciales'}
+                        else 'supply_compatible_media' if error.campo in {'media','duracion','formato'} else 'review_post')
+                diagnostics.append(issue('route_validation',error.motivo,field=error.campo,action=action))
+        except Exception:
+            diagnostics.append(issue('post_invalid','Review the selected platform block and contained media paths.',field='post',action='review_post'))
+        platforms[platform.value]={'status':'blocked' if diagnostics else 'passed','assets':assets,'issues':diagnostics,
+            'requirements_source':SOURCES.get(platform.value,'SocialCli configured route policy'),
+            'coverage':{'provider_acceptance_verified':False,'all_file_bytes_decoded':False,
+                'unchecked':['current account eligibility and grants','remote URL availability',
+                    'full decoder integrity','provider processing and publication outcome'],
+                'local_policy':'Configured size/duration/route limits also apply; they are not a complete provider specification.'}}
+    passed=sum(row['status']=='passed' for row in platforms.values())
+    return {'version':1,'brand':brand.nombre,'slug':slug,'status':'passed' if passed==len(platforms) else 'partial' if passed else 'blocked',
+        'scope':'ordinary post.yml routes; native manifests, Stories and groups have separate validators',
+        'server_media_storage':False,'provider_eligibility_verified':False,'files_modified':False,'platforms':platforms}
+
+
+def register(media_app,default_root):
+    import json
+    import typer
+    from socialctl.brands import cargar_brand
+    from socialctl.agent_errors import error_document
+    @media_app.command('check')
+    def check(slug:str,brand:str=typer.Option(...,'--brand'),root:Path=typer.Option(default_root,'--root'),only:list[Platform]=typer.Option(None,'--only'),json_output:bool=typer.Option(False,'--json')):
+        try:value=check_post(cargar_brand(root,brand),slug,only)
+        except (Exception,KeyboardInterrupt) as exc:
+            value={'version':1,'status':'error','error':error_document(exc,read_only=True)}
+        if json_output:typer.echo(json.dumps(value,ensure_ascii=False,indent=2))
+        elif 'platforms' in value:
+            typer.echo('Local post preflight; no upload or approval. Provider acceptance remains unverified.')
+            for platform,row in value['platforms'].items():
+                typer.echo(f"{platform}: {row['status']}")
+                for problem in row['issues']:typer.echo(f"  {problem['field']}: {problem['message']}")
+        else:typer.echo(value['error']['message'])
+        if value['status']!='passed':raise typer.Exit(1)

socialctl/media_registry.py

@@ -0,0 +1,301 @@
+"""Brand-bound supplied-byte bundles, independent of historical queue migrations."""
+from __future__ import annotations
+
+import hashlib
+import fcntl
+import json
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from contextlib import contextmanager
+
+import yaml
+
+from socialctl.hosted_media import MAX_BYTES, MIMES, file_digest
+from socialctl.migration_files import durable_write, rewrite_media, write_json
+from socialctl.models import CampaignType
+from socialctl.rutas import validar_ruta_relativa
+from socialctl.scheduler import ScheduleStore
+
+MAX_ITEMS = 64
+MAX_TOTAL = 4 * MAX_BYTES
+MAX_POST = 1024 * 1024
+MAX_HEADER = 256 * 1024
+
+
+class MediaRegistryError(ValueError):
+    pass
+
+
+@contextmanager
+def publication_gate(brand, slug: str):
+    """Lock order: executor (if any), this gate, queue mutation, Meta gate."""
+    component(slug)
+    key = digest(canonical(dict(brand=brand.nombre, root=str(brand.raiz.resolve()), slug=slug)))
+    path = relative(brand.raiz, f".socialctl/media-post-gates/{key}.lock")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as exc:
+            raise MediaRegistryError("post is running concurrently; retry after it finishes") from exc
+        yield
+    finally:
+        os.close(fd)
+
+
+def record_publication_start(brand, post, platforms) -> None:
+    if post.brand != brand.nombre:
+        raise MediaRegistryError("post belongs to another brand")
+    path = relative(brand.raiz, f".socialctl/media-publication-started/{component(post.slug)}.json")
+    # Evidence only for ingress draft eligibility, never a publication/retry gate.
+    write_json(path, dict(version=1, brand=brand.nombre, root=str(brand.raiz.resolve()),
+                         slug=post.slug, platforms=[p.value for p in platforms]))
+
+
+def digest(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()
+
+
+def canonical(value: dict) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
+
+
+def parse_json(raw: bytes, *, limit=MAX_HEADER):
+    def unique(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise MediaRegistryError("duplicate JSON keys")
+            result[key] = value
+        return result
+    if len(raw) > limit:
+        raise MediaRegistryError("JSON exceeds the limit")
+    return json.loads(raw, object_pairs_hook=unique)
+
+
+def safe(path: Path) -> Path:
+    """Reject links even when they point within the allowed root."""
+    if any(part.is_symlink() for part in [path, *path.parents]):
+        raise MediaRegistryError("paths containing symbolic links are not supported")
+    if path.exists() and not (path.is_file() or path.is_dir()):
+        raise MediaRegistryError("unsupported file type")
+    return path
+
+
+def relative(root: Path, value: str) -> Path:
+    try:
+        return safe(validar_ruta_relativa(root, value, MediaRegistryError, "media path"))
+    except ValueError as exc:
+        raise MediaRegistryError("invalid media path or symbolic link") from exc
+
+
+def component(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[\w][\w .-]{0,127}", value) or value in {".", ".."}:
+        raise MediaRegistryError("invalid identifier")
+    return value
+
+
+def check_mime(path: Path, suffix: str) -> str:
+    mime = MIMES.get(suffix)
+    with safe(path).open("rb") as handle:
+        head = handle.read(32)
+    recognized = (
+        suffix in {".mp4", ".mov"} and len(head) >= 12 and head[4:8] == b"ftyp"
+        or suffix in {".jpg", ".jpeg"} and head.startswith(b"\xff\xd8\xff")
+        or suffix == ".png" and head.startswith(b"\x89PNG\r\n\x1a\n")
+        or suffix == ".webp" and head[:4] == b"RIFF" and head[8:12] == b"WEBP"
+    )
+    if not mime or not recognized:
+        raise MediaRegistryError("unsupported supplied MIME type or incompatible signature")
+    return mime
+
+
+def check_file(path: Path, item: dict) -> None:
+    safe(path)
+    if (not path.is_file() or path.stat().st_size != item["size"]
+            or file_digest(path) != item["sha256"]
+            or check_mime(path, Path(item["relative_path"]).suffix) != item["mime"]):
+        raise MediaRegistryError("existing bytes do not match SHA-256, size or MIME type")
+
+
+def space(path: Path, size: int) -> None:
+    safe(path)
+    while not path.exists():
+        path = path.parent
+    if shutil.disk_usage(path).free < size + 1024 * 1024:
+        raise MediaRegistryError("insufficient destination space")
+
+
+def copy_exact(incoming, out, size: int) -> None:
+    remaining = size
+    while remaining:
+        chunk = incoming.read(min(remaining, 1024 * 1024))
+        if not chunk or len(chunk) > remaining:
+            raise MediaRegistryError("supplied size changed during copying")
+        out.write(chunk)
+        remaining -= len(chunk)
+    if incoming.read(1):
+        raise MediaRegistryError("supplied size changed during copying")
+
+
+def promote(source: Path, target: Path, item: dict, *, public: bool = False) -> None:
+    """Copy into same-directory temporary inode, fsync then atomic no-clobber link."""
+    safe(target)
+    if target.exists():
+        check_file(target, item)
+        if public and target.stat().st_mode & 0o444 != 0o444:
+            raise MediaRegistryError("existing public copy is unreadable")
+        return
+    space(target.parent, item["size"])
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if public:
+        # Only framework-owned content-address directories are made searchable.
+        for directory in (target.parent, target.parent.parent):
+            directory.chmod(directory.stat().st_mode | 0o555)
+    fd, temporary = tempfile.mkstemp(prefix=".ingress-", dir=target.parent)
+    temp = Path(temporary)
+    try:
+        with os.fdopen(fd, "wb") as out, safe(source).open("rb") as incoming:
+            copy_exact(incoming, out, item["size"])
+            out.flush()
+            os.fchmod(out.fileno(), 0o644 if public else 0o600)
+            os.fsync(out.fileno())
+        check_file(temp, item)
+        try:
+            os.link(temp, target)
+        except FileExistsError:
+            check_file(target, item)
+        ScheduleStore._sync_directory(target.parent)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def validate_manifest(brand, manifest: dict) -> dict:
+    try:
+        if set(manifest) != {"version", "brand", "slug", "post_sha256", "post_size", "assets", "digest"}:
+            raise ValueError()
+        unsigned = {k: v for k, v in manifest.items() if k != "digest"}
+        if (type(manifest["version"]) is not int or manifest["version"] != 1
+                or manifest["brand"] != brand.nombre or manifest["digest"] != digest(canonical(unsigned))):
+            raise ValueError()
+        component(manifest["slug"])
+        if not re.fullmatch(r"[a-f0-9]{64}", manifest["post_sha256"]):
+            raise ValueError()
+        if type(manifest["post_size"]) is not int or not 0 < manifest["post_size"] <= MAX_POST:
+            raise ValueError()
+        assets = manifest["assets"]
+        if not isinstance(assets, list) or not 0 < len(assets) <= MAX_ITEMS:
+            raise ValueError()
+        seen = set()
+        for item in assets:
+            if set(item) != {"sha256", "size", "mime", "source", "relative_path", "uses"}:
+                raise ValueError()
+            sha = item["sha256"]
+            if not re.fullmatch(r"[a-f0-9]{64}", sha):
+                raise ValueError()
+            suffix = Path(item["relative_path"]).suffix
+            if (item["relative_path"] != f"approved/sha256/{sha}{suffix}"
+                    or item["mime"] != MIMES.get(suffix) or suffix not in MIMES
+                    or type(item["size"]) is not int or not 0 < item["size"] <= MAX_BYTES
+                    or item["relative_path"] in seen):
+                raise ValueError()
+            seen.add(item["relative_path"])
+            # Source is provenance only; ingestion never reads this client path.
+            if not item["source"].startswith("media/"):
+                raise ValueError()
+            validar_ruta_relativa(Path("/supplied"), item["source"], MediaRegistryError, "origen")
+            if (not isinstance(item["uses"], list) or not item["uses"] or len(item["uses"]) > 4
+                    or len(set(item["uses"])) != len(item["uses"])
+                    or any(use not in {manifest["slug"] + "/" + p for p in ("youtube", "facebook", "instagram", "tiktok")} for use in item["uses"])):
+                raise ValueError()
+        if sum(item["size"] for item in assets) > MAX_TOTAL:
+            raise ValueError()
+    except (KeyError, TypeError, ValueError) as exc:
+        raise MediaRegistryError("invalid or modified manifest, or manifest belongs to another brand") from exc
+    return manifest
+
+
+def bundle_path(brand, ident: str, suffix=".json") -> Path:
+    if not re.fullmatch(r"[a-f0-9]{64}", ident):
+        raise MediaRegistryError("invalid bundle identifier")
+    return relative(brand.raiz, f".socialctl/media-bundles/{ident}{suffix}")
+
+
+def load_bundle(brand, ident: str) -> tuple[dict, bytes]:
+    manifest = validate_manifest(brand, parse_json(bundle_path(brand, ident).read_bytes()))
+    post = bundle_path(brand, ident, ".yml").read_bytes()
+    if manifest["digest"] != ident or len(post) != manifest["post_size"] or digest(post) != manifest["post_sha256"]:
+        raise MediaRegistryError("bundle was modified")
+    return manifest, post
+
+
+def post_media(raw: bytes) -> dict[str, list[str]]:
+    try:
+        if len(raw) > MAX_POST:
+            raise ValueError()
+        data = yaml.safe_load(raw)
+        platforms = data["platforms"]
+        if not isinstance(platforms, dict) or not platforms or data.get("campaign") not in {v.value for v in CampaignType}:
+            raise ValueError()
+        result = {}
+        for name, block in platforms.items():
+            if name not in {"youtube", "facebook", "instagram", "tiktok"} or not isinstance(block["body"], str):
+                raise ValueError()
+            media = block.get("media", [])
+            if not isinstance(media, list) or any(not isinstance(value, str) for value in media):
+                raise ValueError()
+            result[name] = media
+        # Also rejects aliases, anchors and duplicate mapping keys.
+        rewrite_media(raw, {p: {v: v for v in values} for p, values in result.items() if values})
+        return result
+    except (KeyError, TypeError, ValueError, yaml.YAMLError) as exc:
+        raise MediaRegistryError("invalid supplied post") from exc
+
+
+def stage(brand, slug: str) -> dict:
+    component(slug)
+    safe(brand.raiz)
+    path = relative(brand.raiz, f"posts/{slug}/post.yml")
+    if path.stat().st_size > MAX_POST:
+        raise MediaRegistryError("supplied post exceeds the limit")
+    raw = path.read_bytes()
+    uses = post_media(raw)
+    assets, replacements = {}, {}
+    for platform, values in uses.items():
+        replacements[platform] = {}
+        for name in values:
+            source = relative(brand.raiz / "media", name)
+            if not source.is_file():
+                raise MediaRegistryError("supplied file is missing")
+            size = source.stat().st_size
+            if not 0 < size <= MAX_BYTES:
+                raise MediaRegistryError("supplied size exceeds the limit")
+            suffix = source.suffix.lower()
+            mime = check_mime(source, suffix)
+            sha = file_digest(source)
+            relative_path = f"approved/sha256/{sha}{suffix}"
+            item = assets.setdefault(relative_path, dict(sha256=sha, size=size, mime=mime,
+                source="media/" + name, relative_path=relative_path, uses=[]))
+            use = f"{slug}/{platform}"
+            if use not in item["uses"]:
+                item["uses"].append(use)
+            replacements[platform][name] = relative_path
+    rewritten = rewrite_media(raw, {p: values for p, values in replacements.items() if values})
+    manifest = dict(version=1, brand=brand.nombre, slug=slug, post_sha256=digest(rewritten),
+                    post_size=len(rewritten), assets=list(assets.values()))
+    manifest["digest"] = digest(canonical(manifest))
+    validate_manifest(brand, manifest)
+    space(brand.raiz, sum(item["size"] for item in assets.values()) + len(rewritten))
+    for item in assets.values():
+        promote(relative(brand.raiz, item["source"]), relative(brand.raiz / "media", item["relative_path"]), item)
+    target = bundle_path(brand, manifest["digest"])
+    if target.exists():
+        load_bundle(brand, manifest["digest"])
+    else:
+        durable_write(bundle_path(brand, manifest["digest"], ".yml"), rewritten)
+        write_json(target, manifest)
+    return manifest

socialctl/media_requirements.py

@@ -0,0 +1,52 @@
+"""Checks for ordinary post.yml routes; no repair or provider access."""
+from socialctl.models import MediaKind,Platform
+
+CHROMA_420 = {'yuv420p','yuvj420p','nv12','nv21'} | {
+    f'yuv420p{depth}{endian}' for depth in (9,10,12,14,16) for endian in ('le','be')}
+
+SOURCES={
+    'instagram':'https://developers.facebook.com/documentation/instagram-platform/instagram-graph-api/reference/ig-user/media',
+    'tiktok':'https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide',
+}
+
+
+def technical_issues(platform,asset):
+    issues=[]
+    def issue(code,message):issues.append({'code':code,'action':'supply_compatible_media','retryable':False,'message':message})
+    if platform in {Platform.YOUTUBE,Platform.TIKTOK} and asset.kind is MediaKind.IMAGE:
+        issue('video_required','This SocialCli route uploads videos only; supply an existing video.')
+    if platform is Platform.INSTAGRAM and asset.width and asset.height:
+        ratio=(asset.probe or {}).get('display_ratio',asset.width/asset.height)
+        low,high=(0.8,1.91) if asset.kind is MediaKind.IMAGE else (0.01,10)
+        if ratio is None or not low <= ratio <= high:
+            issue('aspect_ratio','Instagram requires an image ratio from 4:5 to 1.91:1, or a Reel ratio from 0.01:1 to 10:1.')
+    if asset.probe is None:
+        return issues
+    meta=asset.probe
+    codec=meta['video_codec']
+    formats=set((meta['container'] or '').split(','))
+    if platform is Platform.INSTAGRAM and asset.kind is MediaKind.IMAGE:
+        if codec!='mjpeg' or asset.path.suffix.lower() not in {'.jpg','.jpeg'} or not formats & {'image2','jpeg_pipe'}:
+            issue('image_format','Instagram image publishing requires an existing JPEG image.')
+    if asset.kind is MediaKind.VIDEO and platform in {Platform.INSTAGRAM,Platform.TIKTOK}:
+        allowed={'h264','hevc'} if platform is Platform.INSTAGRAM else {'h264','hevc','vp8','vp9'}
+        if codec not in allowed:issue('video_codec','Supply video encoded with '+', '.join(sorted(allowed))+'.')
+        # format_name is a demuxer alias list, not proof of a container subtype.
+        brand=(meta.get('container_brand') or '').strip()
+        iso_brands={'isom','iso2','iso3','iso4','iso5','iso6','iso7','iso8','iso9','mp41','mp42','avc1','M4V','qt'}
+        verified_iso=bool(formats & {'mov','mp4'}) and brand in iso_brands and asset.path.suffix.lower() in {'.mov','.mp4'}
+        if not verified_iso:
+            issue('video_container','Container identity is unsupported or unverified; supply an existing verified MOV/MP4. Ambiguous Matroska/WebM identification is not accepted by this local check.')
+        if meta['fps'] is None or not 23 <= meta['fps'] <= 60:
+            issue('frame_rate','This publishing route requires a verified frame rate between 23 and 60 FPS.')
+        if platform is Platform.TIKTOK and any(not 360 <= v <= 4096 for v in (asset.width,asset.height)):
+            issue('dimensions','TikTok requires both video dimensions between 360 and 4096 pixels.')
+        if platform is Platform.INSTAGRAM:
+            if asset.width>1920:issue('dimensions','Instagram Reels allow at most 1920 horizontal pixels.')
+            if meta['pixel_format'] not in CHROMA_420:
+                issue('pixel_format','This route requires verified 4:2:0 chroma sampling.')
+            for audio in meta['audio']:
+                try:valid=audio['codec']=='aac' and 0<int(audio['sample_rate'])<=48000 and audio['channels'] in {1,2}
+                except (TypeError,ValueError):valid=False
+                if not valid:issue('audio_format','Instagram Reels require AAC audio, at most 48 kHz and one or two channels.')
+    return issues

socialctl/metricas/__init__.py

@@ -0,0 +1,6 @@
+"""Read-only network metrics package; imports register available readers."""
+
+from __future__ import annotations
+
+from socialctl.metricas import facebook, instagram, tiktok, youtube  # noqa: F401
+from socialctl.metricas.base import LECTORES, Lector, SinPermiso, leer_red  # noqa: F401

socialctl/metricas/almacen.py

@@ -0,0 +1,133 @@
+"""Store one brand snapshot per day; historical files can be read manually."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import warnings
+from datetime import date, timedelta
+from pathlib import Path
+
+from socialctl.brands import Brand
+from socialctl.metricas.modelos import Snapshot
+
+
+def escribir_atomico(ruta: Path, texto: str) -> Path:
+    """Atomically replace file using a temporary sibling so interruptions never leave a partially written destination."""
+    ruta.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporal = tempfile.mkstemp(
+        dir=ruta.parent, prefix=f".{ruta.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as fichero:
+            fichero.write(texto)
+            fichero.flush()
+            os.fsync(fichero.fileno())
+        os.replace(temporal, ruta)
+    except BaseException:
+        # Si algo falló antes del `replace`, el destino sigue intacto; lo
+        # único que sobra es el temporal, que no debe quedarse en la carpeta
+        # del usuario.
+        Path(temporal).unlink(missing_ok=True)
+        raise
+    return ruta
+
+
+def dir_metricas(brand: Brand) -> Path:
+    return brand.raiz / "metricas"
+
+
+def ruta_snapshot(brand: Brand, fecha: date) -> Path:
+    return dir_metricas(brand) / f"{fecha.isoformat()}.json"
+
+
+def guardar_snapshot(brand: Brand, snapshot: Snapshot) -> Path:
+    """Write daily snapshot atomically."""
+    return escribir_atomico(
+        ruta_snapshot(brand, snapshot.fecha),
+        snapshot.model_dump_json(indent=2) + "\n",
+    )
+
+
+def cargar_snapshot(brand: Brand, fecha: date) -> Snapshot | None:
+    """Load dated snapshot, or None if absent/unreadable; warn on corrupt files rather than abort all metrics."""
+    from socialctl.youtube_data import enforce_youtube_data
+    enforce_youtube_data(brand.raiz)
+    ruta = ruta_snapshot(brand, fecha)
+    if not ruta.is_file():
+        return None
+    try:
+        return Snapshot.model_validate(json.loads(ruta.read_text(encoding="utf-8")))
+    except Exception as exc:  # noqa: BLE001 - cualquier forma ilegible cuenta
+        warnings.warn(
+            f"snapshot {ruta} cannot be read ({type(exc).__name__}: {exc}); "
+            "ignored, so no comparison with that day is available today. A "
+            "snapshot can be regenerated: delete it and rerun stats for "
+            "today's date, or repair it manually to preserve history.",
+            stacklevel=2,
+        )
+        return None
+
+
+def _fechas(brand: Brand) -> list[date]:
+    """List existing snapshot dates oldest first; ignore non-date JSON filenames."""
+    carpeta = dir_metricas(brand)
+    if not carpeta.is_dir():
+        return []
+    fechas = []
+    for fichero in carpeta.glob("*.json"):
+        try:
+            fechas.append(date.fromisoformat(fichero.stem))
+        except ValueError:
+            continue
+    return sorted(fechas)
+
+
+def ultimo_snapshot(brand: Brand) -> Snapshot | None:
+    fechas = _fechas(brand)
+    return cargar_snapshot(brand, fechas[-1]) if fechas else None
+
+
+def snapshot_anterior(brand: Brand, antes_de: date) -> Snapshot | None:
+    previas = [f for f in _fechas(brand) if f < antes_de]
+    return cargar_snapshot(brand, previas[-1]) if previas else None
+
+
+#: Cuánto histórico de snapshots se conserva. Decisión del usuario, literal:
+#: un año, sin adelgazar los ficheros intermedios -160 MB anuales es un
+#: coste aceptable y la simplicidad vale más que ahorrar unos megas-.
+#:
+#: **Por qué 365 días corridos y no el año natural** (1 de enero a 31 de
+#: diciembre): el año natural haría que el tamaño de la carpeta dependiera
+#: de qué día del año es hoy -el 2 de enero se quedaría con apenas dos
+#: días de histórico, aunque ayer mismo hubiera un año entero-, que es
+#: justo lo contrario de predecible para quien mire la carpeta. Con una
+#: ventana corrida, la carpeta contiene siempre (ejecutando `stats` a
+#: diario) el mismo número de ficheros aproximado y el mismo peso
+#: aproximado, sea hoy el día que sea del calendario; y "un año" significa
+#: lo mismo que en la frase del usuario: 365 días hacia atrás desde hoy,
+#: sin sorpresas de fin de año.
+RETENCION_SNAPSHOTS_DIAS = 365
+
+
+def limpiar_snapshots_antiguos(
+    brand: Brand, hoy: date | None = None
+) -> tuple[list[Path], list[tuple[Path, OSError]]]:
+    """Delete snapshots older than one year; leave piezas.yml and resumen.md unchanged."""
+    hoy = hoy if hoy is not None else date.today()
+    corte = hoy - timedelta(days=RETENCION_SNAPSHOTS_DIAS)
+
+    borrados: list[Path] = []
+    fallidos: list[tuple[Path, OSError]] = []
+    for fecha in _fechas(brand):
+        if fecha >= corte:
+            continue
+        ruta = ruta_snapshot(brand, fecha)
+        try:
+            ruta.unlink()
+        except OSError as exc:
+            fallidos.append((ruta, exc))
+        else:
+            borrados.append(ruta)
+    return borrados, fallidos