socialcli 0.3.0__py3-none-any.whl

socialctl/native_schedule/remote_data.py

@@ -0,0 +1,177 @@
+"""Validate native peer data before exposing approval or operation evidence."""
+import json
+
+from .approval import SCHEMA, hash_value, validate_payload
+from .models import NativeJob, NativeObservation
+
+
+def validate_data(rows, *, command, brand, jobs, request_args):
+    by_id = {job['id']: job for job in jobs}
+    specific = {'approve', 'dispatch', 'reconcile', 'handoff', 'submit-marker', 'cancel', 'reschedule'}
+    expected = request_args[1] if command in specific and len(request_args) > 1 else None
+
+    def shape(value, required, optional=()):
+        if not isinstance(value, dict) or not set(required) <= set(value) or set(value) - set(required) - set(optional):
+            raise ValueError('Invalid native data shape')
+
+    def job(value):
+        parsed = NativeJob.model_validate_json(value if isinstance(value, str) else json.dumps(value))
+        if parsed.brand != brand or expected is not None and parsed.id != expected:
+            raise ValueError('Mismatched native data identity')
+        return parsed
+
+    def target(identifier):
+        if expected is not None and identifier != expected or identifier not in by_id:
+            raise ValueError('Unknown native result target')
+        return by_id[identifier]
+
+    def first_comment(value, known):
+        shape(value, ('status',), ('publication_id','change_id','comment_id'))
+        if value['status'] == 'not_requested':
+            if set(value) != {'status'}:
+                raise ValueError('Invalid unrequested first-comment result')
+            return
+        statuses = {'pending','manual_review','observed_existing','proposed','applying','uncertain',
+                    'rejected','verified','failed','conflict','partial','accepted_unverifiable'}
+        if value['status'] not in statuses:
+            raise ValueError('Unknown native first-comment state')
+        from uuid import UUID
+        try:
+            UUID(value['publication_id'])
+        except (KeyError, ValueError, TypeError, AttributeError):
+            raise ValueError('Invalid native publication recovery ID') from None
+        for key in ('change_id', 'comment_id'):
+            if value.get(key) is not None and (not isinstance(value[key],str) or not value[key].strip()):
+                raise ValueError('Invalid native comment identity')
+        if value['status'] == 'verified' and (known['state'] != 'published'
+                or not value.get('change_id') or not value.get('comment_id')):
+            raise ValueError('Verified native comment lacks published media or durable receipt')
+
+    def approval(value):
+        shape(value, ('schema', 'intent', 'payload', 'media'))
+        if value['schema'] != SCHEMA:
+            raise ValueError('Invalid native approval schema')
+        intent = value['intent']
+        shape(intent, ('brand','platform','account_id','legacy_entry_id','publish_at',
+            'timezone_name','dispatch_after','route','media_hash','content_hash'), ('schedule_mode',))
+        parsed = job(dict(intent, id=expected or 'remote-preview', created_at=intent['dispatch_after'], updated_at=intent['dispatch_after']))
+        validate_payload(parsed.platform, value['payload'])
+        if not isinstance(value['media'], list):
+            raise ValueError('Invalid native media hashes')
+        for media in value['media']:
+            shape(media, ('path', 'sha256'))
+        if hash_value(value['payload']) != parsed.content_hash or hash_value(value['media']) != parsed.media_hash:
+            raise ValueError('Native approval content mismatch')
+
+    def preview(value):
+        shape(value, ('kind','job_id','remote_ref','account_id','platform','route','before','after','payload','consequence'))
+        before, after = job(value['before']), job(value['after'])
+        target(value['job_id'])
+        if (before.id != after.id or before.id != value['job_id'] or before.account_id != after.account_id
+                or before.platform != after.platform or before.remote_id != value['remote_ref']
+                or before.account_id != value['account_id'] or before.platform != value['platform']
+                or value['kind'] not in {'cancel','reschedule'} or value['route'] != 'official_ui'
+                or hash_value(value['payload']) != before.content_hash or before.content_hash != after.content_hash):
+            raise ValueError('Mismatched native action preview')
+        if command in {'cancel','reschedule'} and value['kind'] != command:
+            raise ValueError('Wrong native action kind')
+
+    def action(value):
+        shape(value, ('id','kind','digest','status','job','preview'), ('submitted_at','created_at'))
+        parsed = job(value['job'])
+        preview(value['preview'])
+        if (value['status'] not in {'approved','submitted','confirmed'} or value['kind'] != value['preview']['kind']
+                or value['digest'] != hash_value(value['preview']) or parsed.model_dump(mode='json') != value['preview']['after']):
+            raise ValueError('Invalid native action')
+
+    for annotated in rows:
+        row = {k: v for k, v in annotated.items() if k != 'next_action'}
+        if row.get('source') == 'checkpoint':
+            shape(row, ('job_id','attempt_id','remote_id','source'))
+            # Snapshots may include other jobs in the same explicit brand.
+            known = by_id.get(row['job_id'])
+            if known is None or known['attempt_id'] != row['attempt_id'] or not isinstance(row['remote_id'], str) or not row['remote_id'].strip():
+                raise ValueError('Invalid checkpoint identity')
+        elif command == 'prepare':
+            approval(row)
+        elif command in {'dispatch','reconcile'}:
+            required = ('job_id','state','notices') + (('observations','instruction') if command == 'reconcile' else ())
+            shape(row, required, ('first_comment',))
+            known = target(row['job_id'])
+            if 'first_comment' in row:
+                first_comment(row['first_comment'], known)
+            if row['state'] != known['state'] or not isinstance(row['notices'], list):
+                raise ValueError('Mismatched native result state')
+            for raw in row.get('observations', []):
+                obs = NativeObservation.model_validate_json(json.dumps(raw))
+                if obs.job_id != known['id'] or obs.platform != known['platform'] or obs.account_id != known['account_id']:
+                    raise ValueError('Mismatched native observation')
+        elif command in {'cancel','reschedule'}:
+            if 'document' in row:
+                shape(row, ('document','digest'))
+                preview(row['document'])
+                if row['digest'] != hash_value(row['document']):
+                    raise ValueError('Mismatched action digest')
+            else:
+                action(row)
+        elif command == 'handoff':
+            if 'action' in row:
+                shape(row, ('action','upload_allowed','instruction'))
+                action(row['action'])
+                if row['upload_allowed'] is not False:
+                    raise ValueError('Action handoff must not upload')
+            else:
+                shape(row, ('schema','state','job','payload','schedule','approval_digest','content_hash','media_hash','media','media_integrity','delivery','operator_policy'))
+                shape(row['job'], ('id','brand','platform','account_id'))
+                known = target(row['job']['id'])
+                if row['job'] != {k: known[k] for k in ('id','brand','platform','account_id')}:
+                    raise ValueError('Mismatched handoff identity')
+                for key in ('state','approval_digest','content_hash','media_hash'):
+                    if row[key] != known[key]:
+                        raise ValueError('Mismatched handoff state')
+                from datetime import datetime
+                from zoneinfo import ZoneInfo
+                when = datetime.fromisoformat(known['publish_at'].replace('Z', '+00:00'))
+                shape(row['schedule'], ('local','utc','timezone'))
+                if (row['schema'] != 'socialctl.native-schedule.handoff.v1'
+                        or row['schedule']['timezone'] != known['timezone_name']
+                        or datetime.fromisoformat(row['schedule']['utc'].replace('Z', '+00:00')) != when
+                        or row['schedule']['local'] != when.astimezone(ZoneInfo(known['timezone_name'])).isoformat()):
+                    raise ValueError('Mismatched handoff schedule')
+                if hash_value(row['payload']) != known['content_hash']:
+                    raise ValueError('Mismatched handoff payload')
+        elif command == 'deliver':
+            shape(row, ('delivered','awaiting_ui','instruction'), ('needs_attention','first_comments'))
+            comments = row.get('first_comments',[])
+            if not isinstance(comments,list):
+                raise ValueError('Invalid native first-comment list')
+            by_comment_job = {}
+            for comment in comments:
+                shape(comment, ('job_id','status'), ('publication_id','change_id','comment_id'))
+                known = target(comment['job_id'])
+                if comment['job_id'] in by_comment_job:
+                    raise ValueError('Duplicate native first-comment result')
+                by_comment_job[comment['job_id']] = comment
+                first_comment({k:v for k,v in comment.items() if k != 'job_id'},known)
+            if not isinstance(row['awaiting_ui'], list) or any(target(i)['state'] != 'awaiting_ui' for i in row['awaiting_ui']):
+                raise ValueError('Invalid delivered jobs')
+            attention = row.get('needs_attention', [])
+            if not isinstance(attention, list) or any(target(i)['state'] not in {'blocked', 'uncertain'}
+                    and by_comment_job.get(i,{}).get('status') not in {'uncertain','manual_review','observed_existing','rejected','failed','conflict','applying','partial','accepted_unverifiable'} for i in attention):
+                raise ValueError('Invalid jobs requiring attention')
+        elif command == 'migration-prepare':
+            shape(row, ('version','brand','brand_root','manifest','manifest_hash','inventory','legacy_entries','legacy_results','native_jobs','transfers','excluded','protections','instruction','digest'))
+            if row['version'] != 1 or row['brand'] != brand or row['digest'] != hash_value({k:v for k,v in row.items() if k != 'digest'}):
+                raise ValueError('Invalid migration proposal')
+            for raw in row['native_jobs']:
+                job(raw)
+            for transfer in row['transfers']:
+                job(transfer['job'])
+                approval(transfer['native_preview'])
+        elif command in {'migration-apply','migration-recover'}:
+            shape(row, ('status','digest','publication_approved'), ('prepared','historical_guard_retained'))
+            if row['status'] != 'committed' or row['publication_approved'] is not False or row['digest'] != request_args[request_args.index('--digest')+1]:
+                raise ValueError('Invalid migration result')
+        else:
+            # status/approve/submit-marker emit snapshots only.
+            raise ValueError('Unexpected native result variant')

socialctl/native_schedule/report.py

@@ -0,0 +1,151 @@
+"""Bound native command envelopes; provider state and command exit stay separate."""
+import json
+import sys
+from contextlib import redirect_stdout
+from contextvars import ContextVar
+
+import typer
+
+from socialctl.agent_errors import error_document, error_for_code
+from .approval import reject_secrets
+from .models import NativeJob
+
+active_report = ContextVar('native_report', default=None)
+READ_ONLY = {'status', 'handoff', 'migration-prepare'}
+
+
+def with_action(value):
+    codes = {'prepared': 'approval_required', 'approved': 'native_wait',
+             'waiting_window': 'native_wait', 'ready': 'native_dispatch',
+             'awaiting_ui': 'native_ui_required', 'ui_required': 'native_ui_required',
+             'conflict': 'operation_rejected', 'dispatching': 'operation_uncertain',
+             'uncertain': 'operation_uncertain', 'verifying': 'native_verify',
+             'pending_verification': 'native_verify', 'native_scheduled': 'native_verify',
+             'blocked': 'operation_rejected', 'unsupported': 'unsupported_operation'}
+    result = {k: v for k, v in value.items() if k != 'next_action'}
+    code = codes.get(result.get('state'))
+    if code:
+        result['next_action'] = error_for_code(code, read_only=False)
+    return result
+
+
+def validate_remote(text, *, command, brand, exit_code, request_args=()):
+    if len(text) > 1_000_000:
+        raise ValueError('Oversized native envelope')
+    value = json.loads(text)
+    fields = {'version', 'kind', 'command', 'brand', 'status', 'exit_code', 'data', 'jobs', 'jobs_complete', 'errors'}
+    if (not isinstance(value, dict) or set(value) != fields or type(value['version']) is not int
+            or value['version'] != 1 or value['kind'] != 'native-schedule'
+            or value['command'] != command or value['brand'] != brand
+            or type(value['exit_code']) is not int or value['exit_code'] != exit_code
+            or not 0 <= exit_code <= 255 or value['status'] != ('ok' if exit_code == 0 else 'error')
+            or type(value['jobs_complete']) is not bool):
+        raise ValueError('Mismatched native envelope')
+    for key in ('data', 'jobs', 'errors'):
+        if not isinstance(value[key], list) or any(not isinstance(row, dict) for row in value[key]):
+            raise ValueError('Invalid native envelope rows')
+    for row in value['jobs']:
+        base = {k: v for k, v in row.items() if k != 'next_action'}
+        reject_secrets(base)
+        NativeJob.model_validate_json(json.dumps(base))
+        if base['brand'] != brand:
+            raise ValueError('Mismatched native job brand')
+    for row in value['data']:
+        reject_secrets({k: v for k, v in row.items() if k != 'next_action'})
+    from .remote_data import validate_data
+    validate_data(value['data'], command=command, brand=brand, jobs=value['jobs'], request_args=request_args)
+    # Only internal catalogue codes supply remote action semantics, never an
+    # arbitrary peer's message/action. Data/job safety is checked independently.
+    value['errors'] = [error_for_code(row.get('code'), read_only=command in READ_ONLY) for row in value['errors']]
+    value['jobs'] = [with_action(row) for row in value['jobs']]
+    value['data'] = [with_action(row) for row in value['data']]
+    return value
+
+
+class NativeReport:
+    def __init__(self, command, brand):
+        self.command, self.brand = command, brand
+        self.data, self.jobs, self.errors = [], [], []
+        self.store = None
+        self.started = False
+        self.jobs_complete = False
+        self.remote = None
+
+    def __enter__(self):
+        self.token = active_report.set(self)
+        self.redirect = redirect_stdout(sys.stderr)
+        self.redirect.__enter__()
+        return self
+
+    def bind(self, store):
+        self.store = store
+        self.snapshot()
+
+    def snapshot(self):
+        rows = [job.model_dump(mode='json') for job in self.store.list_jobs()]
+        reject_secrets(rows)
+        self.jobs = [with_action(row) for row in rows]
+        # Durable checkpoints can precede a job's final remote_id (for example,
+        # interruption after upload START). Expose IDs only, never upload URLs.
+        for row in rows:
+            for attempt in self.store.get_attempts(row['id']):
+                checkpoint = attempt['checkpoint']
+                remote_id = checkpoint.get('video_id') or checkpoint.get('remote_id')
+                if remote_id:
+                    evidence = {'job_id': row['id'], 'attempt_id': attempt['id'],
+                                'remote_id': remote_id, 'source': 'checkpoint'}
+                    reject_secrets(evidence)
+                    if evidence not in self.data:
+                        self.data.append(evidence)
+
+    def __exit__(self, kind, exc, traceback):
+        code = 0 if exc is None else (exc.exit_code or 0) if isinstance(exc, typer.Exit) else 130 if isinstance(exc, KeyboardInterrupt) else 1
+        try:
+            if self.remote is None:
+                if exc is not None and code:
+                    known = next((row['next_action'] for row in reversed(self.data)
+                                  if 'next_action' in row), None)
+                    self.errors.append(known if isinstance(exc, typer.Exit) and known else
+                        error_for_code('operation_failed') if isinstance(exc, typer.Exit) else
+                        error_for_code('operation_uncertain') if self.started else
+                        error_document(exc, read_only=self.command in READ_ONLY))
+                if self.store is not None:
+                    try:
+                        self.snapshot()
+                        self.jobs_complete = True
+                    except Exception:
+                        self.errors.append(error_for_code('reporting_incomplete'))
+                        code = code or 1
+                payload = {'version': 1, 'kind': 'native-schedule', 'command': self.command,
+                           'brand': self.brand, 'status': 'ok' if code == 0 else 'error',
+                           'exit_code': code, 'data': self.data, 'jobs': self.jobs,
+                           'jobs_complete': self.jobs_complete, 'errors': self.errors}
+            else:
+                payload = self.remote
+                code = payload['exit_code']
+        finally:
+            active_report.reset(self.token)
+            self.redirect.__exit__(kind, exc, traceback)
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+        if code:
+            raise typer.Exit(code) from None
+        return exc is not None
+
+
+def bind_store(store):
+    report = active_report.get()
+    if report is not None:
+        report.bind(store)
+
+
+def capture(value):
+    report = active_report.get()
+    if report is not None:
+        reject_secrets(value)
+        report.data.append(with_action(value))
+
+
+def begin_submission():
+    report = active_report.get()
+    if report is not None:
+        report.started = True