socialcli 0.3.0__py3-none-any.whl

socialctl/management/community_batches.py

@@ -0,0 +1,294 @@
+"""Immutable supervised community batches; existing child stores own write safety."""
+from __future__ import annotations
+import hashlib
+import hmac
+import json
+import uuid
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from socialctl.management.changes import ChangeError, now_utc
+from socialctl.management.resource_changes import ResourceStore
+from socialctl.models import Platform
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value,sort_keys=True,ensure_ascii=False,separators=(',',':')).encode()).hexdigest()
+
+
+class BatchChild(BaseModel):
+    model_config=ConfigDict(extra='forbid')
+    provider: Literal['youtube-community','meta-comments','meta-management']
+    change_id: str
+    fingerprint: str
+    account_id: str
+    proposal: dict
+    limitations: list[str]
+
+
+class CommunityBatch(BaseModel):
+    model_config=ConfigDict(extra='forbid')
+    version: Literal[1]=1
+    kind: Literal['community-batch']='community-batch'
+    id: str
+    brand: str
+    brand_root: str
+    accounts: dict
+    children: list[BatchChild]=Field(min_length=1,max_length=100)
+    created_at: str
+    fingerprint: str=''
+    status: Literal['proposed','applying','partial','verified']='proposed'
+    outcomes: dict[str,dict]=Field(default_factory=dict)
+
+
+def batch_fingerprint(batch):
+    return digest(batch.model_dump(mode='json',exclude={'fingerprint','status','outcomes'}))
+
+
+class CommunityBatchStore(ResourceStore):
+    model_type=CommunityBatch
+    fingerprint_for=staticmethod(batch_fingerprint)
+    def __init__(self,root):
+        self.root=Path(root)/'.socialctl'/'community-batches'
+
+
+def child_store(brand,provider):
+    if provider=='youtube-community':
+        from socialctl.management.community_changes import CommunityStore
+        return CommunityStore(brand.raiz)
+    if provider=='meta-comments':
+        from socialctl.management.meta_comments import CommentStore
+        return CommentStore(brand.raiz)
+    if provider=='meta-management':
+        from socialctl.management.meta_changes import MetaStore
+        return MetaStore(brand.raiz)
+    raise ChangeError('unsupported community batch provider')
+
+
+def child_details(brand,provider,child):
+    if provider=='youtube-community':
+        if child.edit['action'] not in {'reply','rate'}: raise ChangeError('batch supports YouTube reply/video rating only')
+        name,root,account=child.target_brand,child.brand_root,child.target_account
+        expected=(brand.cuentas.get('youtube') or {}).get('channel_id')
+        target=child.edit.get('parent_id') or child.edit.get('video_id')
+        operation=[provider,account,child.edit['action'],target]
+        limitations=child.effects
+    elif provider=='meta-comments':
+        if child.action not in {'add','reply'}: raise ChangeError('batch supports Meta add/reply only')
+        name,root,account=child.brand,child.brand_root,child.account_id
+        field='page_id' if child.platform=='facebook' else 'ig_user_id'
+        expected=(brand.cuentas.get(child.platform) or {}).get(field)
+        operation=[provider,child.platform,account,child.parent_id or child.media_id]
+        limitations=['Exact supplied text and target only. Clickability/pinning are not promised. Uncertain writes are not repeated.',
+            'Requires actual creator grants and applicable actor/object eligibility; app settings alone do not prove permission.']
+    else:
+        if child.platform!='facebook' or child.edit['action'] not in {'like','unlike'}: raise ChangeError('batch supports Facebook like/unlike only')
+        name,root,account=child.brand,child.brand_root,child.identity['account_id']
+        expected=(brand.cuentas.get('facebook') or {}).get('page_id')
+        operation=[provider,account,child.edit.get('comment_id') or child.edit['target_id']]
+        limitations=['Facebook Page token, pages_manage_engagement and eligible object/Page task required. No rollback or cross-provider transaction.']
+    if (name,root,account)!=(brand.nombre,str(brand.raiz.resolve()),expected):
+        raise ChangeError('child brand/account binding differs from current brand')
+    return account,operation,limitations
+
+
+def prepare_community_batch(brand,child_refs):
+    if not isinstance(child_refs,list) or not 1<=len(child_refs)<=100: raise ChangeError('batch needs 1–100 explicit children')
+    children,seen=[],set()
+    for ref in child_refs:
+        if not isinstance(ref,dict) or set(ref)!={'provider','change_id'}: raise ChangeError('child reference requires provider/change_id only')
+        store=child_store(brand,ref['provider'])
+        child=store.load(ref['change_id'])
+        if child.status!='proposed': raise ChangeError('prepare batch from proposed children only')
+        account,key,limits=child_details(brand,ref['provider'],child)
+        key=digest(key)
+        if key in seen: raise ChangeError('duplicate/conflicting community batch target')
+        seen.add(key)
+        children.append(BatchChild(**ref,fingerprint=child.fingerprint,account_id=account,
+            proposal=child.model_dump(mode='json'),limitations=limits))
+    batch=CommunityBatch(id=str(uuid.uuid4()),brand=brand.nombre,brand_root=str(brand.raiz.resolve()),
+        accounts=brand.cuentas,children=children,created_at=now_utc().isoformat())
+    batch.fingerprint=batch_fingerprint(batch)
+    CommunityBatchStore(brand.raiz).save(batch)
+    return batch
+
+
+def http_client():
+    from socialctl.read_budget import ReadBudget,read_client
+    return read_client(ReadBudget(120))
+
+
+def dispatch(brand,reference,*,reconcile=False):
+    store=child_store(brand,reference.provider)
+    with http_client() as http:
+        if reference.provider=='youtube-community':
+            from socialctl.management.youtube_community import YouTubeCommunityClient
+            from socialctl.management.community_changes import apply_community,reconcile_community
+            client=YouTubeCommunityClient(brand,http)
+            apply,read=apply_community,reconcile_community
+        elif reference.provider=='meta-comments':
+            from socialctl.management.meta_comments import MetaCommentsClient,apply_comment,reconcile_comment
+            client=MetaCommentsClient(brand,Platform(reference.proposal['platform']),http)
+            apply,read=apply_comment,reconcile_comment
+            child=store.load(reference.change_id)
+            if child.inbox_binding:
+                from socialctl.management.meta_comment_inbox import CommentInboxStore, apply_inbox_draft, reconcile_inbox_draft
+                inbox=CommentInboxStore(brand.raiz)
+                records=[r for r in inbox.load().comments if (r.platform,r.account_id,r.media_id,r.comment_id)==
+                    (child.platform,child.account_id,child.media_id,child.parent_id)]
+                if len(records)!=1 or records[0].change_id!=child.id or records[0].fingerprint!=child.fingerprint:
+                    raise ChangeError('inbox draft changed; prepare a new full batch preview')
+                kwargs={'media_id':child.media_id,'comment_id':child.parent_id}
+                if reconcile:
+                    reconcile_inbox_draft(client,store,inbox,**kwargs)
+                else:
+                    apply_inbox_draft(client,store,inbox,approval_digest=reference.fingerprint,**kwargs)
+                return store.load(reference.change_id)
+        else:
+            from socialctl.management.meta_client import MetaClient
+            from socialctl.management.meta_changes import apply_meta,reconcile_meta
+            client=MetaClient(brand,Platform.FACEBOOK,http)
+            apply,read=apply_meta,reconcile_meta
+        if reconcile: return read(client,store,reference.change_id)
+        return apply(client,store,reference.change_id,reference.fingerprint)
+
+
+def validate_batch(brand,batch):
+    if (batch.brand,batch.brand_root,batch.accounts)!=(brand.nombre,str(brand.raiz.resolve()),brand.cuentas):
+        raise ChangeError('batch brand/account configuration changed; prepare a new preview')
+    for ref in batch.children:
+        child=child_store(brand,ref.provider).load(ref.change_id)
+        child_details(brand,ref.provider,child)
+        if not hmac.compare_digest(child.fingerprint,ref.fingerprint):
+            raise ChangeError('child proposal changed; batch approval is invalid')
+
+
+def child_outcome(ref, index, status, **extra):
+    return {'status':status, 'child_index':index, 'provider':ref.provider,
+        'platform':ref.proposal.get('platform', 'youtube'), 'change_id':ref.change_id, **extra}
+
+
+def batch_document(batch, *, brand=None):
+    """Include pending children even when reading a historical sparse journal."""
+    from socialctl.agent_errors import error_for_code
+    value = batch.model_dump(mode='json')
+    outcomes = value['outcomes']
+    for index, ref in enumerate(batch.children, 1):
+        previous = outcomes.get(ref.change_id, {})
+        if brand is not None:
+            current = child_store(brand,ref.provider).load(ref.change_id)
+            if not hmac.compare_digest(current.fingerprint,ref.fingerprint):
+                raise ChangeError('child proposal changed; batch approval is invalid')
+            if current.status != 'proposed':
+                previous = child_outcome(ref,index,current.status) if current.status == 'verified' else {**previous,'status':current.status}
+        outcomes[ref.change_id] = {**child_outcome(ref, index, 'not_attempted'), **previous}
+    groups = {'verified':[], 'pending':[], 'uncertain':[], 'blocked':[]}
+    for ident, outcome in outcomes.items():
+        status = outcome['status']
+        group = ('verified' if status == 'verified' else 'pending' if status in {'not_attempted','proposed'}
+            else 'uncertain' if status in {'applying','uncertain','partial','accepted_unverifiable','applied_unverified'} else 'blocked')
+        groups[group].append(ident)
+    value['summary'] = {'total':len(batch.children), **{f'{key}_{suffix}':len(ids) if suffix == 'count' else ids
+        for key, ids in groups.items() for suffix in ('count','ids')}}
+    if brand is not None:
+        if len(groups['verified']) == len(batch.children):
+            value['status']='verified'
+        elif value['status']=='verified' or any(groups[k] for k in ('verified','uncertain','blocked')):
+            value['status']='partial'
+    if value['status'] != 'verified':
+        if groups['uncertain']:
+            value['error_detail'] = error_for_code('operation_uncertain', read_only=False)
+        elif groups['blocked']:
+            value['error_detail'] = error_for_code('operation_rejected', read_only=False)
+        elif value['status'] == 'proposed':
+            value['error_detail'] = error_for_code('approval_required', read_only=False)
+        elif groups['pending']:
+            value['error_detail'] = {'code':'batch_pending', 'action':'apply_remaining',
+                'retryable':False, 'requires_user_action':False,
+                'message':'Continue the existing approved batch with its exact fingerprint. Verified children will be skipped; do not create a new batch.'}
+    return value
+
+
+def report_progress(callback, ref, index, total, status):
+    if callback is not None:
+        try:
+            callback({**child_outcome(ref, index, status), 'total':total})
+        except Exception:
+            pass  # UI diagnostics never alter durable write safety.
+
+
+def apply_community_batch(brand,batch_id,approval_digest,*,progress=None):
+    store=CommunityBatchStore(brand.raiz)
+    with store.apply_lock(batch_id):
+        batch=store.load(batch_id)
+        if not isinstance(approval_digest,str) or not hmac.compare_digest(batch.fingerprint,approval_digest):
+            raise ChangeError('approval must match the exact full batch fingerprint')
+        validate_batch(brand,batch)
+        for index, ref in enumerate(batch.children, 1):
+            batch.outcomes.setdefault(ref.change_id, child_outcome(ref, index, 'not_attempted'))
+        for index, ref in enumerate(batch.children, 1):
+            child=child_store(brand,ref.provider).load(ref.change_id)
+            if child.status=='verified':
+                batch.outcomes[ref.change_id]=child_outcome(ref, index, 'verified')
+                report_progress(progress, ref, index, len(batch.children), 'verified')
+                continue
+            batch.status='applying'
+            batch.outcomes[ref.change_id]=child_outcome(ref, index, 'applying')
+            store.save(batch)
+            report_progress(progress, ref, index, len(batch.children), 'applying')
+            try:
+                result=dispatch(brand,ref)
+                # A received receipt permits bounded read-only verification,
+                # never another write. Normal provider readback can lag the POST.
+                # Lost receipts and contradictory/unavailable evidence still stop
+                # this sequential batch before its next child.
+                if (result.status in {'uncertain', 'applied_unverified', 'accepted_unverifiable'}
+                        and (getattr(result, 'remote_id', None) or getattr(result, 'result_id', None))):
+                    report_progress(progress, ref, index, len(batch.children), 'verifying_receipt')
+                    result=dispatch(brand,ref,reconcile=True)
+                batch.outcomes[ref.change_id]=child_outcome(ref, index, result.status)
+                report_progress(progress, ref, index, len(batch.children), result.status)
+            except ChangeError as exc:
+                from socialctl.read_reports import safe_error
+                from socialctl.agent_errors import error_document
+                current = child_store(brand,ref.provider).load(ref.change_id)
+                state = current.status if current.status in {'applying','uncertain','partial','accepted_unverifiable','applied_unverified'} else 'blocked'
+                batch.outcomes[ref.change_id]=child_outcome(ref, index, state,
+                    error=safe_error(str(exc)), error_detail=error_document(exc, read_only=True))
+                report_progress(progress, ref, index, len(batch.children), state)
+                batch.status='partial';store.save(batch);return batch
+            except BaseException:
+                batch.status='partial';store.save(batch);raise
+            if result.status!='verified':
+                batch.status='partial';store.save(batch);return batch
+            store.save(batch)
+        batch.status='verified';store.save(batch);return batch
+
+
+def reconcile_community_batch(brand,batch_id,*,progress=None):
+    store=CommunityBatchStore(brand.raiz)
+    with store.apply_lock(batch_id):
+        batch=store.load(batch_id);validate_batch(brand,batch)
+        for index, ref in enumerate(batch.children, 1):
+            child=child_store(brand,ref.provider).load(ref.change_id)
+            if child.status == 'proposed':
+                batch.outcomes.setdefault(ref.change_id, child_outcome(ref, index, 'not_attempted'))
+                continue
+            if child.status in {'applying','uncertain','partial','accepted_unverifiable','applied_unverified'}:
+                try:
+                    child=dispatch(brand,ref,reconcile=True)
+                except ChangeError as exc:
+                    from socialctl.read_reports import safe_error
+                    from socialctl.agent_errors import error_document
+                    current=child_store(brand,ref.provider).load(ref.change_id)
+                    batch.outcomes[ref.change_id]=child_outcome(ref,index,current.status,
+                        error=safe_error(str(exc)),error_detail=error_document(exc,read_only=True))
+                    report_progress(progress,ref,index,len(batch.children),current.status)
+                    store.save(batch)
+                    continue
+            batch.outcomes[ref.change_id]=child_outcome(ref, index, child.status)
+            report_progress(progress, ref, index, len(batch.children), child.status)
+            store.save(batch)
+        batch.status='verified' if all(batch.outcomes.get(ref.change_id,{}).get('status')=='verified' for ref in batch.children) else 'partial'
+        store.save(batch);return batch

socialctl/management/community_changes.py

@@ -0,0 +1,370 @@
+"""Durable exact approval, per-target moderation observations and no blind retry."""
+import hmac
+import json
+import uuid
+from contextlib import ExitStack
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from socialctl.management.changes import ApprovalMismatch, now_utc
+from socialctl.management.community_schema import CommentTarget, edit_raw, opaque_id, validate_edit
+from socialctl.management.resource_changes import ResourceStore, fingerprint, _event
+from socialctl.management.youtube_community import complete, FILTERS
+from socialctl.management.youtube_resources import ResourceError, ResourceConflict, ResourceRejected, ResourceUncertain, resource_id
+
+
+class CommunityChange(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    version: Literal[1] = 1
+    kind: Literal["youtube-community"] = "youtube-community"
+    id: str
+    target_brand: str
+    brand_root: str
+    target_account: str
+    edit: dict
+    before: dict
+    after: dict
+    effects: list[str]
+    fingerprint: str = ""
+    created_at: datetime
+    updated_at: datetime
+    status: Literal["proposed", "applying", "uncertain", "failed", "conflict", "verified", "partial", "accepted_unverifiable"] = "proposed"
+    verified: bool = False
+    result_id: str | None = None
+    receipt: dict | None = None
+    journal: list[dict] = Field(default_factory=list)
+
+
+class CommunityStore(ResourceStore):
+    model_type = CommunityChange
+    fingerprint_for = staticmethod(fingerprint)
+
+    def __init__(self, brand_root):
+        self.root = Path(brand_root) / ".socialctl" / "youtube-community"
+
+
+def binding(edit):
+    return {k: getattr(edit, k) for k in ("video_id", "thread_id", "comment_id", "parent_id") if getattr(edit, k) is not None}
+
+
+def author(row):
+    value = row["snippet"].get("authorChannelId")
+    if not isinstance(value, dict) or not isinstance(value.get("value"), str) or not value["value"]:
+        raise ResourceError("comment author unverifiable")
+    return resource_id(value["value"])
+
+
+def baseline(client, edit):
+    action = edit.action
+    if action in {"add", "reply"}:
+        video = client.inspect(edit.video_id)
+        before = {"video_id": edit.video_id, "owner": video.channel_id}
+        if action == "reply":
+            thread = client.thread(edit.video_id, edit.thread_id)
+            if thread["snippet"]["topLevelComment"]["id"] != edit.parent_id or thread["snippet"].get("canReply") is not True:
+                raise ResourceError("parent mismatch or thread does not accept replies")
+            before["parent"] = thread["snippet"]["topLevelComment"]
+            report = client.list_replies(edit.video_id, edit.thread_id, edit.parent_id)
+            if not report['complete']:
+                # Only the missing-envelope case permits preparation. Invalid identities,
+                # contradictory metadata and uncertain pagination still block a write.
+                if not str(report.get('error', '')).startswith('pagination metadata missing'):
+                    complete(report)
+                before['reply_coverage'] = {'complete':False, 'absence_proven':False,
+                    'limitation':'Reply enumeration lacks metadata; existing remote duplicates cannot be ruled out.'}
+            rows = report['items']
+        else:
+            rows = []
+            for state in FILTERS:
+                rows.extend(t["snippet"]["topLevelComment"] for t in complete(client.list_threads(edit.video_id, moderation_status=state)))
+        if any(r["snippet"].get("authorChannelId", {}).get("value") == client.configured_channel_id
+            and r["snippet"].get("textOriginal") == edit.text for r in rows):
+            raise ResourceConflict("owned comment with exact text already exists at target; do not duplicate")
+        return before
+    if action in {"edit", "delete"}:
+        row = client.find_comment(**binding(edit))
+        if author(row) != client.configured_channel_id:
+            raise ResourceError("only original author can edit/delete; another author requires explicit moderation")
+        if action == "edit" and not isinstance(row["snippet"].get("textOriginal"), str):
+            raise ResourceError("author textOriginal missing; textDisplay is not original text")
+        return {"comment": row}
+    if action == "moderate":
+        rows = []
+        cache = {}
+        for target in edit.targets:
+            row = client.find_comment(**target.model_dump(exclude_none=True), moderation=True, cache=cache)
+            author(row)
+            previous = row["snippet"].get("moderationStatus")
+            if previous not in {"heldForReview", "published", "likelySpam", "rejected"}:
+                raise ResourceError("previous moderation status unverifiable")
+            if previous == "rejected" and edit.moderation_status != "rejected":
+                raise ResourceError("transition from rejected unsupported; restoration is not promised")
+            if edit.moderation_status == "heldForReview" and previous in {"published", "rejected"}:
+                raise ResourceError("transition to heldForReview unsupported from published/rejected")
+            rows.append({"target": target.model_dump(exclude_none=True), "comment": row})
+        return {"targets": rows}
+    if action in {"subscribe", "unsubscribe"}:
+        target = client.external("channels", edit.channel_id)
+        if edit.channel_id == client.configured_channel_id:
+            raise ResourceError("YouTube does not allow subscribing to your own channel")
+        rows = [r for r in complete(client.list_subscriptions()) if r["snippet"]["resourceId"]["channelId"] == edit.channel_id]
+        if action == "subscribe" and rows:
+            raise ResourceConflict("subscription already exists")
+        if action == "unsubscribe" and (len(rows) != 1 or rows[0]["id"] != edit.subscription_id):
+            raise ResourceError("subscription_id does not match actor and target")
+        return {"target": target, "subscriptions": rows}
+    if action == "rate":
+        return {"rating": client.get_rating(edit.video_id)}
+    if action == "report-abuse":
+        target = client.external("videos", edit.video_id)
+        reasons = complete(client.catalog("abuse-reasons", language=edit.language or "en"))
+        rows = [r for r in reasons if r["id"] == edit.reason_id]
+        if len(rows) != 1:
+            raise ResourceError("reason_id is absent from public catalog")
+        if edit.secondary_reason_id and not any(r.get("id") == edit.secondary_reason_id for r in rows[0]["snippet"].get("secondaryReasons", []) if isinstance(r, dict)):
+            raise ResourceError("secondary_reason_id does not belong to approved reason")
+        return {"target": target, "reason": rows[0]}
+    raise ResourceError("unsupported action")
+
+
+def body_for(edit, account):
+    if edit.action == "add":
+        return {"snippet": {"channelId": account, "videoId": edit.video_id,
+            "topLevelComment": {"snippet": {"textOriginal": edit.text}}}}
+    if edit.action == "reply":
+        return {"snippet": {"parentId": edit.parent_id, "textOriginal": edit.text}}
+    if edit.action == "edit":
+        return {"id": edit.comment_id, "snippet": {"textOriginal": edit.text}}
+    if edit.action == "subscribe":
+        return {"snippet": {"resourceId": {"kind": "youtube#channel", "channelId": edit.channel_id}}}
+    if edit.action == "report-abuse":
+        return {k: v for k, v in {"videoId": edit.video_id, "reasonId": edit.reason_id,
+            "secondaryReasonId": edit.secondary_reason_id, "comments": edit.comments, "language": edit.language}.items() if v is not None}
+    return {}
+
+
+def effects_for(edit):
+    notes = ["Only exact supplied IDs, actor, text and values. YouTube validates effective grants/eligibility; no permissions granted.",
+        "Status preflight before writing; remote race possible. Provider If-Match atomicity is not guaranteed.",
+        "Uncertain outcome not repeated with another UUID. Reconcile only reads."]
+    if edit.action in {"add", "reply", "edit"}:
+        notes.append("Comment visibility depends on privacy/moderation. textOriginal is verified only for its author; textDisplay does not prove original text. Pin, heart and clickable links are not promised.")
+    if edit.action == "delete":
+        notes.append("Original author's comment deletion; snapshot cannot be restored. Replies may become hidden. Absence does not prove deletion.")
+    if edit.action == "moderate":
+        notes.append("One POST for up to 50 explicit comments; individual checks. Rejected also hides replies; restoration is not promised. No automatic selection or rollback.")
+        notes.append("banAuthor=true automatically rejects future comments from EACH displayed author." if edit.ban_author else "banAuthor=false: future author blocking is not requested.")
+        notes.append("204 is an acceptance receipt; absence or invisible status does not prove status or banAuthor. Individual readback may remain partial/unverifiable.")
+    if edit.action in {"subscribe", "unsubscribe"}:
+        notes.append("Authenticated actor differs from external target channel. YouTube prevents self-subscription and duplicates and may limit volume/eligibility.")
+    if edit.action == "rate":
+        notes.append("Actor rating on explicit video, including external videos; none removes rating. Does not change official like/dislike count. Verified email required; rental/disabled ratings may prevent it.")
+    if edit.action == "report-abuse":
+        notes.append("Explicit video REPORT with displayed reason, independent of comments/audit. 204 accepts submission; no report query or guarantee of sanctions/reversal.")
+    return notes
+
+
+def prepare_community(client, store, edit, *, reply_context=None):
+    edit = validate_edit(edit)
+    account = client.identity()
+    before = baseline(client, edit)
+    if reply_context is not None:
+        from socialctl.management.reply_context import verify_reply_context
+        verify_reply_context(client, reply_context, media_id=edit.video_id,
+            parent_id=edit.parent_id, thread_id=edit.thread_id)
+        before['reply_context'] = reply_context
+    moment = now_utc()
+    change = CommunityChange(id=str(uuid.uuid4()), target_brand=client.brand.nombre, brand_root=str(client.brand.raiz.resolve()),
+        target_account=account, edit=edit_raw(edit), before=before, after=body_for(edit, account), effects=effects_for(edit), created_at=moment, updated_at=moment)
+    change.fingerprint = fingerprint(change)
+    _event(change, "prepared")
+    store.save(change)
+    return change
+
+
+def identity(client, change):
+    if (client.brand.nombre, str(client.brand.raiz.resolve()), client.configured_channel_id) != (change.target_brand, change.brand_root, change.target_account):
+        raise ResourceError("brand/account differs from proposal")
+    if client.identity() != change.target_account:
+        raise ResourceError("authenticated actor mismatch")
+
+
+def operation_keys(change):
+    edit = validate_edit(change.edit)
+    if edit.action == "moderate":
+        keys = [("comments", t.video_id) for t in edit.targets]
+    elif edit.action in {"add", "reply", "edit", "delete"}:
+        keys = [("comments", edit.video_id)]
+    elif edit.action in {"subscribe", "unsubscribe"}:
+        keys = [("subscriptions", edit.channel_id)]
+    else:
+        keys = [(edit.action, edit.video_id)]
+    return {json.dumps([change.target_account, *key]) for key in keys}
+
+
+def receipt_for(client, change, response):
+    edit = validate_edit(change.edit)
+    if response.get("http_status") == 204:
+        return response
+    receipt = {"identity_valid": False}
+    try:
+        if edit.action == "add":
+            receipt["thread_id"] = opaque_id(response.get("id"))
+            row = response["snippet"]["topLevelComment"]
+            change.result_id = opaque_id(row.get("id"))
+            client._thread(response, edit.video_id)
+        elif edit.action in {"reply", "edit"}:
+            row = response
+            change.result_id = opaque_id(row.get("id"))
+            client._comment(row, parent=edit.parent_id)
+            if edit.action == "edit" and change.result_id != edit.comment_id:
+                return receipt
+        else:
+            change.result_id = opaque_id(response.get("id"))
+            client._subscription(response)
+            receipt["identity_valid"] = response["snippet"]["resourceId"]["channelId"] == edit.channel_id
+            return receipt
+        receipt["identity_valid"] = author(row) == change.target_account
+    except (ResourceError, KeyError, TypeError, AttributeError):
+        pass
+    return receipt
+
+
+def readback(client, store, change):
+    edit = validate_edit(change.edit)
+    try:
+        identity(client, change)
+        receipt = change.receipt or {}
+        if edit.action == "moderate" and receipt.get("http_status") == 204:
+            observations = []
+            cache = {}
+            for target in edit.targets:
+                observed = {"target": target.model_dump(exclude_none=True), "matches": False}
+                try:
+                    row = client.find_comment(**target.model_dump(exclude_none=True), moderation=True, cache=cache)
+                    observed["moderation_status"] = row["snippet"].get("moderationStatus")
+                    observed["matches"] = observed["moderation_status"] == edit.moderation_status
+                    prior = next(r["comment"] for r in change.before["targets"] if r["target"]["comment_id"] == target.comment_id)
+                    observed["matches"] = observed["matches"] and author(row) == author(prior)
+                except ResourceError as exc:
+                    observed["error"] = str(exc)
+                observations.append(observed)
+                _event(change, "moderation_target_readback", observation=observed, ban_verified=False)
+                store.save(change)  # Each observed target survives later readback failure.
+            matches = sum(o["matches"] for o in observations)
+            _event(change, "moderation_readback", observations=observations, ban_verified=False)
+            change.status = "partial" if 0 < matches < len(observations) else "accepted_unverifiable"
+            if matches == len(observations) and not edit.ban_author:
+                change.status, change.verified = "verified", True
+        elif edit.action in {"delete", "report-abuse"} and receipt.get("http_status") == 204:
+            change.status = "accepted_unverifiable"
+            if edit.action == "delete":
+                observation = {"absence_is_not_proof": True}
+                try:
+                    row = client.find_comment(**binding(edit))
+                    observation["comment_still_observed"] = row["id"]
+                except ResourceError as exc:
+                    observation["readback_error"] = str(exc)
+                _event(change, "delete_readback", **observation)
+            else:
+                _event(change, "accepted_without_provable_readback", no_report_read_endpoint=True)
+        elif edit.action in {"subscribe", "unsubscribe"}:
+            rows = complete(client.list_subscriptions())
+            rows = [r for r in rows if r["snippet"]["resourceId"]["channelId"] == edit.channel_id]
+            matches = (not rows and receipt.get("http_status") == 204) if edit.action == "unsubscribe" else (
+                receipt.get("identity_valid") and len(rows) == 1 and rows[0]["id"] == change.result_id)
+            _event(change, "subscription_readback", matches=bool(matches))
+            if matches:
+                change.status, change.verified = "verified", True
+        elif edit.action == "rate":
+            current = client.get_rating(edit.video_id)
+            _event(change, "rating_readback", observed=current)
+            if receipt.get("http_status") == 204 and current["rating"] == edit.rating:
+                change.status, change.verified = "verified", True
+        elif receipt.get("identity_valid") and change.result_id:
+            target = {"video_id": edit.video_id, "thread_id": receipt.get("thread_id", edit.thread_id),
+                "comment_id": change.result_id, "parent_id": edit.parent_id}
+            row = client.find_comment(**target, allow_partial=True)
+            matches = author(row) == change.target_account and row["snippet"].get("textOriginal") == edit.text
+            _event(change, "comment_readback", matches=matches, comment_id=change.result_id)
+            if matches:
+                change.status, change.verified = "verified", True
+        else:
+            _event(change, "identity_unresolved", no_candidate_adoption=True)
+    except ResourceError as exc:
+        _event(change, "readback_unavailable", error=str(exc))
+    store.save(change)
+    return change
+
+
+def reconcile_community(client, store, change_id):
+    with store.apply_lock(change_id):
+        change = store.load(change_id)
+        identity(client, change)
+        if change.status in {"applying", "uncertain", "partial", "accepted_unverifiable"}:
+            if change.status == "applying":
+                change.status = "uncertain"
+            return readback(client, store, change)
+        return change
+
+
+def apply_community(client, store, change_id, approval_digest):
+    with ExitStack() as locks:
+        locks.enter_context(store.apply_lock(change_id))
+        change = store.load(change_id)
+        edit = validate_edit(change.edit)
+        if not hmac.compare_digest(approval_digest, change.fingerprint):
+            raise ApprovalMismatch("approval does not match exact fingerprint")
+        if body_for(edit, change.target_account) != change.after or effects_for(edit) != change.effects:
+            raise ResourceError("body/effects do not match proposal")
+        keys = operation_keys(change)
+        for key in sorted(keys):
+            locks.enter_context(store.apply_lock(str(uuid.uuid5(uuid.NAMESPACE_URL, key))))
+        identity(client, change)
+        if change.status != "proposed":
+            if change.status in {"applying", "uncertain", "partial", "accepted_unverifiable"}:
+                if change.status == "applying":
+                    change.status = "uncertain"
+                return readback(client, store, change)
+            return change
+        for path in store.root.glob("*.json"):
+            other = store.load(path.stem)
+            if other.id != change.id and keys & operation_keys(other) and other.status in {"applying", "uncertain", "partial"}:
+                raise ResourceError(f"uncertain outcome pending in {other.id}; another UUID does not allow repetition")
+            if (other.id != change.id and other.status == "verified"
+                    and other.target_account == change.target_account
+                    and edit.action in {"add", "reply"}
+                    and other.edit == change.edit):
+                raise ResourceConflict("identical comment already verified locally; another UUID does not allow repetition")
+        try:
+            if change.before.get('reply_context'):
+                from socialctl.management.reply_context import verify_reply_context
+                verify_reply_context(client, change.before['reply_context'], media_id=edit.video_id,
+                    parent_id=edit.parent_id, thread_id=edit.thread_id)
+            if baseline(client, edit) != {k:v for k,v in change.before.items() if k != 'reply_context'}:
+                raise ResourceConflict("conflict: status/author changed since preview")
+        except ResourceConflict:
+            change.status = "conflict"
+            _event(change, "pre_write_conflict")
+            store.save(change)
+            raise
+        change.status = "applying"
+        _event(change, "write_intent", approval_digest=approval_digest)
+        store.save(change)
+        try:
+            response = client.effect(edit, change.after, change.before)
+        except ResourceRejected as exc:
+            change.status = "conflict" if isinstance(exc, ResourceConflict) else "failed"
+            _event(change, "write_rejected", error=str(exc))
+        except ResourceUncertain as exc:
+            change.status = "uncertain"
+            _event(change, "write_uncertain", error=str(exc))
+        else:
+            change.status = "uncertain"
+            change.receipt = receipt_for(client, change, response)
+            _event(change, "write_response", result_id=change.result_id, receipt=change.receipt)
+        store.save(change)
+        return readback(client, store, change) if change.status == "uncertain" else change