socialcli 0.3.0__tar.gz → 0.3.1__tar.gz

{socialcli-0.3.0 → socialcli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: socialcli
-Version: 0.3.0
+Version: 0.3.1
 Summary: SocialCli: publish and manage creator-owned social content from the terminal.
 Project-URL: Homepage, https://socialcli.app
 Project-URL: Repository, https://github.com/engels-florentino/SocialCli
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 
 # SocialCli
 
-**Current source version: 0.3.0.** SocialCli SaaS is the current SocialCli
+**Current source version: 0.3.1 (release preparation).** SocialCli SaaS is the current SocialCli
 product. The repository root on `main` is its single development workspace;
 the CLI, hosted connection service and account/billing components live together
 here. Earlier versions remain in Git history for reference and migration.
@@ -61,9 +61,9 @@ Stripe uses test mode. Planned access costs
 USD 10/month after 14 free days from the first successful connection. No real
 subscriptions are collected in this pilot.
 
-The current client release target is **0.3.0** (published first to TestPyPI and
-then to PyPI through the reviewed release workflow). The compatible hosted
-runtime is `socialcli-saas-candidate:45fda63`. The client's wheel and
+The next client release target is **0.3.1**, pending reviewed publication through
+TestPyPI and PyPI. The currently published stable client remains **0.3.0**.
+The hosted service is managed and verified separately from the CLI release. The client's wheel and
 source archive are verified against the
 reviewed build hashes before publication. Provider commercial approvals and live
 billing cutover remain separate from package publication. See the

{socialcli-0.3.0 → socialcli-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 # SocialCli
 
-**Current source version: 0.3.0.** SocialCli SaaS is the current SocialCli
+**Current source version: 0.3.1 (release preparation).** SocialCli SaaS is the current SocialCli
 product. The repository root on `main` is its single development workspace;
 the CLI, hosted connection service and account/billing components live together
 here. Earlier versions remain in Git history for reference and migration.
@@ -38,9 +38,9 @@ Stripe uses test mode. Planned access costs
 USD 10/month after 14 free days from the first successful connection. No real
 subscriptions are collected in this pilot.
 
-The current client release target is **0.3.0** (published first to TestPyPI and
-then to PyPI through the reviewed release workflow). The compatible hosted
-runtime is `socialcli-saas-candidate:45fda63`. The client's wheel and
+The next client release target is **0.3.1**, pending reviewed publication through
+TestPyPI and PyPI. The currently published stable client remains **0.3.0**.
+The hosted service is managed and verified separately from the CLI release. The client's wheel and
 source archive are verified against the
 reviewed build hashes before publication. Provider commercial approvals and live
 billing cutover remain separate from package publication. See the

{socialcli-0.3.0 → socialcli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "socialcli"
-version = "0.3.0"
+version = "0.3.1"
 description = "SocialCli: publish and manage creator-owned social content from the terminal."
 readme = "README.md"
 license = "MIT"

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/agent_errors.py

@@ -32,6 +32,10 @@ _ACTIONS = {
 # Only fixed internal codes acquire action semantics. Provider text is diagnostic,
 # never a command, an expiry signal or evidence that a write was not accepted.
 _CATALOG = {
+    'reply_history_purged': ('user_action', 'Prior reply evidence was removed by retention. Review the preserved journal and platform before any new draft. Do not delete replay-blocking markers or repeat an uncertain write.'),
+    'dry_run_required': ('correct_input', 'inbox-draft requires --dry-run to prepare a preview. No provider content write was started.'),
+    'reply_input_invalid': ('correct_input', 'Use a version 1 reply file with a nonempty replies list (1–100 items). Each reply requires platform, account_id, comment_id and text. media_id is read from the inbox, not supplied in this file.'),
+    'target_validation_failed': ('inspect', 'Local target verification failed. Inspect the diagnostic reason; this does not establish a provider rejection or invalid credentials.'),
     'approval_mismatch': ('user_action', 'The supplied approval does not match this exact preview. Obtain the owner approval before applying.'),
     'approval_required': ('user_action', 'Show the complete preview and obtain explicit approval of its exact fingerprint.'),
     'operation_cancelled': ('inspect', 'Approval was cancelled. No write was started by this command.'),
@@ -108,6 +112,7 @@ def error_document(exc: BaseException, *, read_only: bool) -> dict:
     from socialctl.management.meta_schema import MetaError, MetaUncertain
     from socialctl.metricas.base import SinPermiso
     from socialctl.youtube_data import YouTubeDataBusy, YouTubeDataCleanupError
+    from socialctl.identity import ReadError
 
     # A read flow may refresh a token via POST. A lost response to that operation
     # cannot be classified as a harmless GET retry merely from the CLI command.
@@ -124,7 +129,7 @@ def error_document(exc: BaseException, *, read_only: bool) -> dict:
             429:'rate_limited',503:'provider_unavailable'}.get(exc.status,'service_rejected')
     elif isinstance(exc, (ResourceUncertain, YouTubeUpdateUncertain, CommentUncertain, MetaUncertain)):
         code = 'operation_uncertain'
-    elif isinstance(exc, (AuthError, YouTubeManagementError, ResourceError, CommentError, MetaError)) and getattr(exc, '_socialcli_error_code', None) is not None:
+    elif isinstance(exc, (AuthError, YouTubeManagementError, ChangeError, ResourceError, CommentError, MetaError, ReadError)) and getattr(exc, '_socialcli_error_code', None) is not None:
         code = exc._socialcli_error_code
     elif isinstance(exc, ReadDeadlineExceeded): code = 'read_deadline'
     elif isinstance(exc, ReadResponseTooLarge): code = 'response_too_large'
@@ -144,21 +149,66 @@ def error_document(exc: BaseException, *, read_only: bool) -> dict:
                 429:'rate_limited'}.get(status,'provider_unavailable' if status>=500 else 'request_rejected')
                 if type(status) is int else 'operation_rejected')
     elif isinstance(exc, httpx.RequestError): code = 'provider_response_invalid'
+    elif isinstance(exc, ReadError):
+        code = {'credentials_missing': 'authorization_unavailable', 'credentials_expired': 'authorization_unavailable',
+                'permission_denied': 'permissions_required', 'rate_limited': 'rate_limited',
+                'timeout': 'transport_failure', 'transport_error': 'transport_failure',
+                'invalid_response': 'provider_response_invalid', 'provider_error': 'provider_unavailable',
+                'configuration_missing': 'account_not_configured'}.get(exc.code, 'target_validation_failed')
+    elif isinstance(exc, ResourceError): code = 'target_validation_failed'
     elif isinstance(exc, ChangeError): code = 'operation_rejected'
     elif isinstance(exc, YouTubeDataBusy): code = 'local_data_busy'
     elif isinstance(exc, (OSError, YouTubeDataCleanupError)): code = 'storage_failure'
     elif isinstance(exc, ValueError): code = 'invalid_local_state'
     else: code = 'operation_failed'
-    return error_for_code(code,read_only=read_only)
+    result = error_for_code(code,read_only=read_only)
+    # Local validation is not evidence of a rejection by the hosted service.
+    if code == 'operation_rejected' and not isinstance(exc, ServiceRejected):
+        result['message'] = _CATALOG[code][1]
+    diagnostic = safe_diagnostic(getattr(exc, '_socialcli_diagnostic', None))
+    if isinstance(exc, ChangeError) and not diagnostic:
+        diagnostic = {'source': 'local'}
+    if isinstance(exc, ServiceRejected):
+        diagnostic.update(source='socialcli', http_status=exc.status)
+    elif isinstance(exc, httpx.HTTPStatusError):
+        diagnostic.update(http_status=exc.response.status_code, request_method=exc.request.method)
+    if diagnostic:
+        result['diagnostic'] = safe_diagnostic(diagnostic)
+    return result
+
+
+def safe_diagnostic(value):
+    """Allow only fixed machine labels, never URLs, bodies, headers or prose."""
+    if not isinstance(value, dict):
+        return {}
+    allowed = {
+        'source': {'local', 'socialcli', 'youtube'},
+        'stage': {'input_validation', 'workspace_read', 'file_read', 'credential_read', 'identity_read', 'provider_read', 'provider_write', 'target_read', 'reply_coverage', 'proposal_preparation', 'baseline_check', 'readback'},
+        'request_method': {'GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE'},
+        'operation': {'channels', 'videos', 'comments', 'commentThreads', 'playlistItems'},
+        'write_state': {'not_started', 'unknown', 'accepted'},
+        'content_write_state': {'not_started'},
+        'reason': {'thread_unverifiable', 'thread_identity_mismatch', 'thread_total_unverifiable', 'comment_binding_mismatch', 'parent_mismatch', 'replies_not_allowed', 'incomplete_reply_list', 'readback_mismatch'},
+        'provider_reason': {'commentsDisabled', 'quotaExceeded', 'dailyLimitExceeded', 'rateLimitExceeded', 'userRateLimitExceeded', 'insufficientPermissions', 'forbidden', 'authError', 'invalidValue', 'videoNotFound', 'commentNotFound', 'commentThreadNotFound', 'processingFailure', 'operationNotSupported'},
+    }
+    clean = {key: val for key, val in value.items()
+             if key in allowed and isinstance(val, str) and val in allowed[key]}
+    status = value.get('http_status')
+    if type(status) is int and 100 <= status <= 599:
+        clean['http_status'] = status
+    return clean
 
 
 def with_error_code(wrapper: Exception, cause: BaseException, *, read_only: bool,
                     fallback: str | None = None) -> Exception:
     """Keep only a fixed code across a sanitized wrapper, never raw exception data."""
-    code = error_document(cause, read_only=read_only)['code']
+    detail = error_document(cause, read_only=read_only)
+    code = detail['code']
     if code == 'operation_failed' and fallback is not None:
         code = error_for_code(fallback, read_only=read_only)['code']
     wrapper._socialcli_error_code = code
+    if detail.get('diagnostic'):
+        wrapper._socialcli_diagnostic = detail['diagnostic']
     return wrapper
 
 
@@ -166,7 +216,28 @@ def with_http_error_code(wrapper: Exception, response, *, read_only: bool) -> Ex
     import httpx
     cause = httpx.HTTPStatusError('Provider request rejected', request=response.request,
                                   response=response)
-    return with_error_code(wrapper, cause, read_only=read_only)
+    wrapper = with_error_code(wrapper, cause, read_only=read_only)
+    if response.request.url.host == 'www.googleapis.com':
+        diagnostic = {'source': 'youtube', 'http_status': response.status_code,
+            'request_method': response.request.method,
+            'stage': 'provider_read' if read_only else 'provider_write',
+            'operation': response.request.url.path.rsplit('/', 1)[-1],
+            'write_state': 'not_started' if read_only else 'unknown'}
+        try:
+            reasons = response.json().get('error', {}).get('errors', [])
+            for row in reasons[:16]:
+                reason = safe_diagnostic({'provider_reason': row.get('reason')}) if isinstance(row, dict) else {}
+                if reason:
+                    diagnostic.update(reason)
+                    if reason['provider_reason'] in {'quotaExceeded', 'dailyLimitExceeded', 'rateLimitExceeded', 'userRateLimitExceeded'}:
+                        wrapper._socialcli_error_code = 'rate_limited' if read_only else 'operation_uncertain'
+                    elif reason['provider_reason'] == 'commentsDisabled' and read_only:
+                        wrapper._socialcli_error_code = 'comments_disabled'
+                    break
+        except (ValueError, TypeError, AttributeError):
+            pass
+        wrapper._socialcli_diagnostic = safe_diagnostic(diagnostic)
+    return wrapper
 
 
 def emit_error(exc: Exception, *, read_only: bool) -> None:

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/agent_guide.py

@@ -3,11 +3,11 @@ from importlib.resources import files
 import re
 
 TOPICS={
-    'setup':('Install the reviewed candidate','Authorize the installation, then the social account','Persist and recover','Publication gate','Explicit approval and preflight'),
+    'setup':('What agents can do','Install the reviewed release','Authorize the installation, then the social account','Persist and recover','Publication gate','Explicit approval and preflight'),
     'publish':('Publication gate','Temporary Instagram media','Canonical publishing workflow','Check supplied media locally','Explicit approval and preflight'),
     'schedule':('Publication gate','Temporary Instagram media','Scheduling and temporary media','Native scheduling input examples (offline)','Explicit approval and preflight'),
-    'inbox':('Publication gate','Read metrics and prepare engagement','Read diagnostics','Comment API corrections','Explicit approval and preflight','Resumable batches and reply context'),
-    'errors':('Persist and recover','Recovery and error actions','Read diagnostics','Comment API corrections','Explicit approval and preflight','Resumable batches and reply context'),
+    'inbox':('Publication gate','Read metrics and prepare engagement','Read diagnostics','Comment API evidence and limits','Explicit approval and preflight','Resumable batches and reply context','Purged reply history'),
+    'errors':('Persist and recover','Recovery and error actions','Read diagnostics','Comment API evidence and limits','Explicit approval and preflight','Resumable batches and reply context','Purged reply history'),
     'permissions':('Installation connection access',),
 }
 
@@ -20,4 +20,4 @@ def guide(topic):
     sections=re.split(r'(?=^## )',full,flags=re.MULTILINE)
     chosen=[section for section in sections if any(section.startswith('## '+heading) for heading in TOPICS[topic])]
     return ('# SocialCli agent guide: '+topic+'\n\n'+''.join(chosen)+
-            '\nNext: socialcli agent-guide publish; socialcli agent-guide schedule; socialcli agent-guide inbox; socialcli agent-guide errors.\n')
+            '\nNext: socialcli agent-guide publish; socialcli agent-guide schedule; socialcli agent-guide inbox; socialcli agent-guide errors; socialcli agent-guide permissions; socialcli agent-guide all.\n')

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/engagement.py

@@ -1,4 +1,5 @@
 """Join observed comments to existing immutable reply journals; never send replies."""
+import json
 import uuid
 
 from socialctl.inbox import UnifiedInboxStore
@@ -17,17 +18,25 @@ class DraftSelectionError(ChangeError):
     def __init__(self, reason, message):
         super().__init__(message)
         self.reason = reason
+        if reason in {'reply_file_schema', 'reply_count', 'invalid_reply_selection'}:
+            self._socialcli_error_code = 'reply_input_invalid'
+        elif reason == 'reply_history_purged':
+            self._socialcli_error_code = reason
 
 
 def draft_failure(exc, row, index, stage):
     # Fixed local reason codes and target IDs only. Provider/storage exception
     # text can contain credentials or private diagnostics and is not copied.
-    exc.draft_failure = {'child_index': index, 'stage': stage,
+    exc.draft_failure = {'child_index': index, 'stage': 'selection' if stage == 'selection' else 'preparation', 'step': stage,
         **{key: row[key] for key in ('platform', 'account_id', 'comment_id', 'media_id')
            if isinstance(row, dict) and isinstance(row.get(key), str)},
         'reason': getattr(exc, 'reason', 'target_validation_failed' if stage == 'selection' else 'draft_preparation_failed')}
     if isinstance(exc, (DraftSelectionError, ReplyCoverageError)):
         exc.draft_failure['message'] = str(exc)
+    from socialctl.agent_errors import safe_diagnostic, error_document
+    write_state = 'unknown' if error_document(exc, read_only=True)['code'] == 'operation_uncertain' else 'not_started'
+    exc._socialcli_diagnostic = {**safe_diagnostic(getattr(exc, '_socialcli_diagnostic', None)),
+        'stage': stage, 'write_state': write_state, 'content_write_state': 'not_started'}
     return exc
 
 
@@ -35,12 +44,46 @@ def http_client(budget):
     return read_client(budget)
 
 
+def purged_history(store, path):
+    """Read only a retention marker's supplied intent, never resurrect its receipt.
+
+    Markers intentionally no longer prove account identity or a write outcome.
+    A matching parent therefore blocks a new draft conservatively across accounts;
+    an unbound marker blocks YouTube drafts, but not the read-only review.
+    """
+    raw = json.loads(path.read_bytes())
+    if not isinstance(raw, dict) or raw.get('data_lifecycle') != 'purged':
+        return None
+    store._validate_id(path.stem)
+    if (raw.get('id') != path.stem or raw.get('platform') != 'youtube'
+            or raw.get('replay_blocked') is not True or not isinstance(raw.get('user_input'), dict)):
+        exc = ChangeError('Invalid purged journal; preserve the file for manual review.')
+        exc._socialcli_error_code = 'invalid_local_state'
+        raise exc
+    from socialctl.management.community_schema import ACTIONS, opaque_id
+    edit = raw['user_input'].get('edit')
+    action = edit.get('action') if isinstance(edit, dict) else None
+    if isinstance(action, str) and action in ACTIONS and action != 'reply':
+        return {'change_id': path.stem, 'reply': False, 'parent_id': None}
+    parent = edit.get('parent_id') if isinstance(edit, dict) and action == 'reply' else None
+    try:
+        parent = opaque_id(parent)
+    except ValueError:
+        parent = None
+    return {'change_id': path.stem, 'reply': True, 'parent_id': parent}
+
+
 def review_inbox(brand):
     data=UnifiedInboxStore(brand.raiz).load()
-    links={};excluded_proposals=0
+    links={};excluded_proposals=0;purged=[]
     for provider in ('youtube-community','meta-comments'):
         store=child_store(brand,provider)
         for path in sorted(store.root.glob('*.json')):
+            if provider == 'youtube-community':
+                history = purged_history(store, path)
+                if history is not None:
+                    purged.append(history)
+                    continue
             child=store.load(path.stem)
             if provider=='youtube-community':
                 if child.edit['action']!='reply':continue
@@ -67,6 +110,7 @@ def review_inbox(brand):
                 context_key = UnifiedInboxStore.key(context)
                 links.setdefault(context_key, []).append({**links[key][-1], 'reply_parent_id':parent})
     items=[];excluded=0
+    unbound = [p for p in purged if p['reply'] and p['parent_id'] is None]
     for key,row in sorted(data['items'].items()):
         field=ACCOUNT_FIELDS.get(row['platform'])
         if not field or row['account_id']!=(brand.cuentas.get(row['platform']) or {}).get(field):
@@ -79,23 +123,32 @@ def review_inbox(brand):
         states={p['status'] for p in proposals}
         evidence=bound_evidence(row)
         platform_replied=bool(evidence and evidence['state']=='owner_reply_found')
-        state=('uncertain' if states & UNCERTAIN else 'replied' if 'verified' in states or platform_replied
+        history = [p['change_id'] for p in purged if row['platform'] == 'youtube' and p['reply']
+                   and (p['parent_id'] is None or p['parent_id'] in {row['comment_id'], row.get('parent_id')})]
+        state=('blocked' if history else 'uncertain' if states & UNCERTAIN else 'replied' if 'verified' in states or platform_replied
                else 'draft' if 'proposed' in states else 'blocked' if states else 'observed')
-        items.append({**row,'reply_state':state,'platform_reply_state':evidence['state'] if evidence else 'unknown','proposals':proposals})
+        items.append({**row,'reply_state':state,'platform_reply_state':evidence['state'] if evidence else 'unknown','proposals':proposals,
+                      'history_review_required':bool(history),'purged_proposals':history})
     return {'version':1,'brand':brand.nombre,'status':'ok','items':items,
         'coverage':{'source':'saved_observations','live_verified':False,'complete':False,
             'excluded_accounts':excluded,'excluded_proposals':excluded_proposals,'watermarks':data['watermarks'],
+            'purged_proposals':len(purged),'unbound_purged_proposals':len(unbound),
             'limitations':['This is saved evidence, not a complete live inbox.',
                 'Replied means a stored verified write or scoped owner reply observed on the platform; present remote visibility is not rechecked. Unknown platform reply state never proves absence.',
+                'Purged journals remain replay-blocked. Matching or unbound reply history requires manual review before a new draft; unrelated comments remain usable.',
                 'TikTok comments are unsupported. Replying in an existing reply thread requires an explicit reply_parent_id mapping to its observed top-level comment; deeper nesting is not promised.']}}
 
 
 def selected_replies(brand,raw):
     if not isinstance(raw,dict) or set(raw)!={'version','replies'} or type(raw['version']) is not int or raw['version']!=1:
-        raise ChangeError('expected version 1 and explicit replies')
+        raise DraftSelectionError('reply_file_schema', 'expected version 1 and explicit replies')
     replies=raw['replies']
-    if not isinstance(replies,list) or not 1<=len(replies)<=100:raise ChangeError('select 1–100 explicit replies')
-    rows={UnifiedInboxStore.key(row):row for row in review_inbox(brand)['items']}
+    if not isinstance(replies,list) or not 1<=len(replies)<=100:raise DraftSelectionError('reply_count', 'select 1–100 explicit replies')
+    try:
+        rows={UnifiedInboxStore.key(row):row for row in review_inbox(brand)['items']}
+    except Exception as exc:
+        exc._socialcli_diagnostic={'source':'local', 'stage':'workspace_read', 'write_state':'not_started'}
+        raise
     result=[];seen=set()
     for index, reply in enumerate(replies, 1):
         try:
@@ -128,6 +181,9 @@ def selected_replies(brand,raw):
                 seen.add(parent_key)
             elif reply.get('reply_parent_id'):
                 raise DraftSelectionError('reply_parent_mismatch', 'reply_parent_id is only valid for an observed nested context')
+            if row.get('history_review_required') or (source and source.get('history_review_required')):
+                raise DraftSelectionError('reply_history_purged',
+                    'Prior reply evidence was removed by retention. Review the preserved journal and platform before any new draft; do not delete the replay-blocking marker.')
             if row['reply_state'] in {'replied','uncertain'}:raise DraftSelectionError('existing_reply_state', 'existing replied/uncertain target; inspect or reconcile before another draft')
             if row.get('author_id') == row['account_id']:
                 raise DraftSelectionError('own_comment', 'target is an own comment')
@@ -155,6 +211,7 @@ def prepare_replies(brand,raw,*,budget,prepared,progress=None):
         selected=selected_replies(brand,raw)
         with http_client(budget) as http:
             for index, (row,text) in enumerate(selected, 1):
+                stage = 'target_read'
                 try:
                     budget.check()
                     if progress is not None:
@@ -168,7 +225,9 @@ def prepare_replies(brand,raw,*,budget,prepared,progress=None):
                         snippet=parent['snippet']
                         same_parent(row,{'id':parent['id'],'author_id':(snippet.get('authorChannelId') or {}).get('value'),
                             'text':snippet.get('textOriginal',snippet.get('textDisplay'))})
+                        stage = 'reply_coverage'
                         check_reply_coverage(client, row)
+                        stage = 'proposal_preparation'
                         child=prepare_community(client,child_store(brand,'youtube-community'),
                             dict(action='reply',video_id=row['media_id'],thread_id=row['thread_id'],parent_id=row['comment_id'],text=text),
                             reply_context=row.get('reply_context'))
@@ -178,6 +237,7 @@ def prepare_replies(brand,raw,*,budget,prepared,progress=None):
                         from socialctl.management.meta_comment_inbox import CommentInboxStore,prepare_inbox_draft
                         client=MetaCommentsClient(brand,Platform(row['platform']),http)
                         same_parent(row,client.find_comment(row['media_id'],row['comment_id']))
+                        stage = 'proposal_preparation'
                         child,_=prepare_inbox_draft(client,child_store(brand,'meta-comments'),CommentInboxStore(brand.raiz),
                             media_id=row['media_id'],comment_id=row['comment_id'],text=text,
                             reply_context=row.get('reply_context'),
@@ -188,6 +248,7 @@ def prepare_replies(brand,raw,*,budget,prepared,progress=None):
                     # Recheck the exact baseline captured by preparation against the
                     # selected observation, not just the earlier network read.
                     parent=child.before['parent']
+                    stage = 'baseline_check'
                     fresh=parent if provider=='meta-comments' else {'id':parent['id'],
                         'author_id':(parent['snippet'].get('authorChannelId') or {}).get('value'),
                         'text':parent['snippet'].get('textOriginal',parent['snippet'].get('textDisplay'))}
@@ -196,5 +257,5 @@ def prepare_replies(brand,raw,*,budget,prepared,progress=None):
                         progress({'child_index':index, 'total':len(selected), 'platform':row['platform'],
                             'comment_id':row['comment_id'], 'status':'prepared'})
                 except (Exception, KeyboardInterrupt) as exc:
-                    raise draft_failure(exc, row, index, 'preparation')
+                    raise draft_failure(exc, row, index, stage)
         return prepare_community_batch(brand,prepared)

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/engagement_cli.py

@@ -32,14 +32,34 @@ def register(app,default_root):
     @app.command('inbox-draft')
     def draft(file:Path=typer.Option(...,'--file'),brand:str=typer.Option(...,'--brand'),root:Path=typer.Option(default_root,'--root'),dry_run:bool=typer.Option(False,'--dry-run'),json_output:bool=typer.Option(False,'--json'),timeout:float=typer.Option(120,'--timeout')):
         prepared=[]
+        stage='input_validation'
         try:
-            if not dry_run:raise ChangeError('drafting requires --dry-run and complete preview before separate approval')
+            if not dry_run:
+                exc=ChangeError('drafting requires --dry-run and complete preview before separate approval')
+                exc._socialcli_error_code='dry_run_required'
+                raise exc
+            stage='workspace_read'
             selected=cargar_brand(root,brand)
+            stage='file_read'
             with file.open('rb') as stream:
                 raw=stream.read(262145)
-            if len(raw)>262144:raise ChangeError('reply file exceeds 256 KiB')
-            batch=prepare_replies(selected,yaml.safe_load(raw),budget=ReadBudget(timeout),prepared=prepared,progress=progress)
+            if len(raw)>262144:
+                exc=ChangeError('reply file exceeds 256 KiB')
+                exc._socialcli_error_code='reply_input_invalid'
+                raise exc
+            stage='input_validation'
+            try:
+                document=yaml.safe_load(raw)
+            except (yaml.YAMLError, UnicodeError):
+                exc=ChangeError('reply file must be valid YAML')
+                exc._socialcli_error_code='reply_input_invalid'
+                raise exc from None
+            batch=prepare_replies(selected,document,budget=ReadBudget(timeout),prepared=prepared,progress=progress)
         except (Exception,KeyboardInterrupt) as exc:
+            if not getattr(exc, 'draft_failure', None):
+                from socialctl.agent_errors import safe_diagnostic
+                exc._socialcli_diagnostic={'source':'local', 'stage':stage, 'write_state':'not_started',
+                    **safe_diagnostic(getattr(exc, '_socialcli_diagnostic', None)), 'content_write_state':'not_started'}
             value={'version':1,'status':'partial' if prepared else 'error','brand':brand,
                 'batch':None,'prepared':prepared,'error':error_document(exc,read_only=True)}
             if getattr(exc, 'draft_failure', None):

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/identity.py

@@ -79,8 +79,12 @@ class IdentityClient:
                 self._token = broker_access_token(brand, platform, client, refresh=False)
             else:
                 self._token = secret.get("access_token")
-        except Exception:
-            raise ReadError("credentials_invalid") from None
+        except Exception as exc:
+            from socialctl.agent_errors import error_document, with_error_code
+            detail = error_document(exc, read_only=True)
+            error = with_error_code(ReadError(detail['code']), exc, read_only=True)
+            error._socialcli_diagnostic = {**detail.get('diagnostic', {}), 'stage': 'credential_read'}
+            raise error from None
         if not isinstance(self._token, str) or not self._token:
             raise ReadError("credentials_missing")
         if self.metadata["expiry"]["expired"]:
@@ -102,12 +106,20 @@ class IdentityClient:
             response = self.client.get(f"{base}/{endpoint}", params=params,
                 headers={"Authorization": f"Bearer {self._token}"}, timeout=30,
                 follow_redirects=False)
-        except httpx.TimeoutException:
-            raise ReadError("timeout") from None
-        except Exception:
-            raise ReadError("transport_error") from None
+        except Exception as exc:
+            from socialctl.agent_errors import error_document, with_error_code
+            detail = error_document(exc, read_only=True)
+            legacy_code = 'timeout' if isinstance(exc, httpx.TimeoutException) else detail['code']
+            error = with_error_code(ReadError(legacy_code), exc, read_only=True)
+            error._socialcli_diagnostic = {**detail.get('diagnostic', {}),
+                'stage': 'provider_read', 'request_method': 'GET'}
+            raise error from None
+        def rejected(code):
+            from socialctl.agent_errors import with_http_error_code
+            error = with_http_error_code(ReadError(code), response, read_only=True)
+            return error
         if response.status_code == 429:
-            raise ReadError("rate_limited")
+            raise rejected("rate_limited")
         if response.status_code in {401, 403}:
             # YouTube quota exhaustion commonly uses HTTP403.
             try:
@@ -116,12 +128,12 @@ class IdentityClient:
             except Exception:
                 reasons = []
             if set(reasons) & {"quotaExceeded", "dailyLimitExceeded", "rateLimitExceeded", "userRateLimitExceeded"}:
-                raise ReadError("rate_limited")
-            raise ReadError("permission_denied")
+                raise rejected("rate_limited")
+            raise rejected("permission_denied")
         if response.status_code == 404:
-            raise ReadError("not_found_or_inaccessible")
+            raise rejected("not_found_or_inaccessible")
         if not response.is_success:
-            raise ReadError("provider_error")
+            raise rejected("provider_error")
         try:
             data = response.json()
             if not isinstance(data, dict):
@@ -193,8 +205,13 @@ def auth_status(brand, platform, client):
         result["identity"] = probe.verify()
     except ReadError as exc:
         result["failure_class"] = exc.code
+        from socialctl.agent_errors import error_document
+        if getattr(exc, '_socialcli_error_code', None):
+            result['error_detail'] = error_document(exc, read_only=True)
         if probe is not None and probe.identity is not None:
             result["identity"] = probe.identity
-    except Exception:
-        result["failure_class"] = "credentials_invalid"
+    except Exception as exc:
+        from socialctl.agent_errors import error_document
+        result['error_detail'] = error_document(exc, read_only=True)
+        result["failure_class"] = result['error_detail']['code']
     return result

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/inbox.py

@@ -80,7 +80,7 @@ class InboxInterrupted(KeyboardInterrupt):
 
 def _partial_problem(report):
     detail = annotate_partial_read({**report, 'complete': False})['error_detail']
-    return {'code': detail['code'], 'message': safe_error(report.get('error') or 'Read incomplete')}
+    return {**detail, 'message': safe_error(report.get('error') or 'Read incomplete')}
 
 
 def _exception_problem(exc):
@@ -90,6 +90,7 @@ def _exception_problem(exc):
 def _problem_document(problem):
     if isinstance(problem, dict):
         return {'code': problem.get('code', 'read_partial'),
+                **({'diagnostic': problem['diagnostic']} if problem.get('diagnostic') else {}),
                 'message': safe_error(problem.get('message', 'Read incomplete'))}
     return {'message': safe_error(str(problem))}
 
@@ -202,6 +203,9 @@ def sync_brand_inbox(brand,*,since,budget,only=None):
                         if resume and inventory['failure_class'] in {'invalid_cursor','provider_error'}:
                             budget.check()
                             inventory=sync_content(brand,platform,http,resume=False)
+                        if inventory.get('failure_class'):
+                            errors.append({'platform': 'youtube',
+                                **inventory.get('error_detail', {'code': 'read_partial', 'message': 'Video inventory incomplete.'})})
                         media=[v['remote_id'] for v in InventoryStore(brand,platform,account).list_items() if v.get('last_sync_id')==inventory['sync_id']]
                         complete=inventory['complete'] and inventory['details_complete']
                         client=YouTubeInboxClient(brand,http)

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/inventory.py

@@ -103,6 +103,7 @@ def sync_content(brand, platform, client, *, max_pages=20, resume=False):
                    "next_cursor": None, "cursors": [], "seen_ids": [], "pages": 0,
                    "missing_resource_ids": [], "resumable": True}
         run["failure_class"] = None
+        run.pop('error_detail', None)
         run["identity"] = identity
         for _ in range(max_pages):
             requested = run["next_cursor"]
@@ -110,6 +111,8 @@ def sync_content(brand, platform, client, *, max_pages=20, resume=False):
                 items, following, missing, source = read_page(probe, requested)
             except ReadError as exc:
                 run["failure_class"] = exc.code
+                from socialctl.agent_errors import error_document
+                run['error_detail'] = error_document(exc, read_only=True)
                 break
             observed_at = now()
             for row in items:
@@ -147,6 +150,7 @@ def sync_content(brand, platform, client, *, max_pages=20, resume=False):
         return {"version": 1, "brand": brand.nombre, "platform": platform.value,
                 "account_id": probe.account_id, "identity": identity, "sync_id": run["id"],
                 "complete": run["complete"], "failure_class": run["failure_class"],
+                **({'error_detail': run['error_detail']} if run.get('failure_class') and run.get('error_detail') else {}),
                 "pagination_complete": run["complete"],
                 "details_complete": run["complete"] and not run["missing_resource_ids"],
                 "resume_available": run["resumable"], "pages": run["pages"],

{socialcli-0.3.0 → socialcli-0.3.1}/socialctl/management/batches.py

@@ -258,18 +258,28 @@ def _apply_operation(client, store, batch, op):
         # validation rejections get a fixed message, never arbitrary exception text.
         diagnostic = exc.diagnostic or {"error": "Metadata validation rejected the update before PUT."}
         _event(op, "write_rejected", **diagnostic)
-    except Exception:
+    except Exception as exc:
         op.status = "uncertain"
-        _event(op, "write_uncertain")
+        from socialctl.agent_errors import error_document
+        _event(op, "write_uncertain", error_detail_json=json.dumps(error_document(exc, read_only=False), sort_keys=True))
     else:
-        try:
-            verified = client.inspect(op.video_id)
-            mismatches = _mismatch_paths(verified, op.after)
-            op.status = "uncertain" if mismatches else "applied"
-            _event(op, "read_back_" + op.status, mismatch_paths=", ".join(mismatches))
-        except Exception:
-            op.status = "uncertain"
-            _event(op, "read_back_unavailable")
+        from socialctl.management.snippet_readback import readback_attempts
+        for attempt in readback_attempts():
+            try:
+                verified = client.inspect(op.video_id)
+                mismatches = _mismatch_paths(verified, op.after)
+                op.status = "uncertain" if mismatches else "applied"
+                _event(op, "read_back_" + op.status, mismatch_paths=", ".join(mismatches), attempt=str(attempt))
+                store.save(batch)
+                if not mismatches:
+                    break
+            except Exception as exc:
+                from socialctl.agent_errors import error_document
+                detail = error_document(exc, read_only=True)
+                op.status = "uncertain"
+                _event(op, "read_back_unavailable", error_detail_json=json.dumps(detail, sort_keys=True), attempt=str(attempt))
+                if not detail['retryable']:
+                    break
     store.save(batch)