@topolo/cli 0.13.19 → 0.13.22

package/agent-packs/src/topolo_agent_pack/cloud_cutover.py

@@ -0,0 +1,134 @@
+"""Closed idle legacy-to-cloud cutover; no worker adoption or local fallback."""
+import hashlib,json,os,pathlib,sqlite3,subprocess,uuid
+from .storage import PackError,atomic_json,canonical,read_json,sync_directory
+from .work import require,TERMINAL
+from .cloud_work import TABLES
+CAPABILITY='topolo-work-cutover-v1'
+
+def digest(value):return hashlib.sha256(canonical(value)).hexdigest()
+def birth(pid):
+    value=subprocess.run(['/bin/ps','-p',str(pid),'-o','lstart=','-o','command='],capture_output=True,text=True,check=True).stdout.strip()
+    require(bool(value),'Native process identity unavailable');return value
+
+def snapshot(db):
+    tables={name:[list(row) for row in db.execute('SELECT * FROM '+name+' ORDER BY '+('sequence' if name=='events' else 'rowid'))] for name in TABLES}
+    retained=[list(row) for row in db.execute('SELECT id,body FROM retained ORDER BY rowid')]
+    require(all(json.loads(row[2])['state'] in TERMINAL for row in tables['tasks']),'Task phases remain pending; preserve the current owner')
+    for row in tables['workers']:
+        w=json.loads(row[2]);require(w['state']=='archived' and w.get('nativeArchived') is True or w['state']=='failed' and not w.get('turnId') and (not w.get('nativeId') or w.get('nativeArchived') is True),'Native worker closure is unresolved')
+    return {'tables':tables,'retained':{'count':len(retained),'sha256':digest(retained)}}
+
+def closure():
+    base=pathlib.Path(__file__).parent
+    return digest({name:hashlib.sha256((base/name).read_bytes()).hexdigest() for name in ['cloud_cutover.py','work.py','work_native.py','live.py']})
+
+def freeze(owner):
+    """Only the current guarded native Broker calls this while its lock is held."""
+    store=owner.work.store;require(not getattr(store,'cloud',False),'Cloud authority is already selected')
+    path=store.root/'cutover.json';require(not path.exists(),'Existing cutover must be reconciled without replay')
+    require(owner.work.cutover_closure==closure(),'Executing native guard source changed; upgrade the idle owner first')
+    with store.db() as db:
+        state=snapshot(db)
+        record={'format':CAPABILITY,'operationId':str(uuid.uuid4()),'root':str(owner.lib.root.resolve()),'pid':os.getpid(),'birth':birth(os.getpid()),'runtime':str(owner.runtime),'tokenDigest':hashlib.sha256(owner.token.encode()).hexdigest(),'guardDigest':owner.work.cutover_closure,'sourceDigest':digest(state),'snapshot':state,'state':'source-fenced-native-stop-unverified'}
+        require(len(canonical(record))<=900000,'Cutover checkpoint exceeds native acknowledgement bound')
+        atomic_json(path,record)
+    return record
+
+def acknowledge(owner,record):
+    require(owner.quiesced and not owner.active_turns and not owner.pending and owner.child is not None and owner.child.returncode is not None,'Native shutdown is not verified')
+    record={**record,'state':'quiesced','childPid':owner.child.pid,'childReturnCode':owner.child.returncode}
+    atomic_json(owner.work.store.root/'cutover.json',record);return record
+
+def source(root,observe):
+    root=pathlib.Path(root).resolve();path=root/'work/cutover.json';st=path.lstat()
+    require(path.is_file() and not path.is_symlink() and st.st_uid==os.getuid() and st.st_mode&0o777==0o600,'Cutover journal must be private and owned')
+    record=read_json(path)
+    if record.get('format')=='topolo-closed-ledger-fence-v1':
+        from .closed_ledger_fence import verify
+        return verify(root)
+    require(record['format']==CAPABILITY and record['root']==str(root) and record['state']=='quiesced','Native cutover acknowledgement is incomplete')
+    actual=observe(root)
+    require(actual==record and birth(record['pid'])==record['birth'] and record['guardDigest']==closure(),'Authenticated executing native cutover generation changed')
+    dbpath=root/'work/tasks.sqlite';require(dbpath.is_file() and not dbpath.is_symlink(),'Native source database changed')
+    db=sqlite3.connect('file:'+str(dbpath)+'?mode=ro',uri=True)
+    try:db.execute('BEGIN');state=snapshot(db)
+    finally:db.close()
+    require(digest(state)==record['sourceDigest']==digest(record['snapshot']),'Fenced legacy source changed')
+    return record
+
+def merge(state,capture):
+    """Retain existing cloud portable checkpoints; exact identities admit delta."""
+    tables={}
+    for name in TABLES:
+        original=state['tables'][name];rows=capture['tables'][name];local={r[0]:r for r in rows}
+        for old in original:
+            require(old[0] in local,'Cloud identity is absent from the final legacy snapshot');current=local[old[0]]
+            if name=='tasks':
+                a,b=json.loads(old[2]),json.loads(current[2]);require(old[1]==current[1] and all(a.get(k)==b.get(k) for k in ['id','revision','state','phase','objective','channel','canonicalClaimId']),'Previously captured task changed; explicit reconciliation required')
+            elif name=='workers':
+                a,b=json.loads(old[2]),json.loads(current[2]);require(old[1]==current[1] and all(a.get(k)==b.get(k) for k in ['id','taskId','phase','attempt','state','nativeId','turnId','nativeArchived']),'Previously captured worker changed; preserve its receipt')
+            else:require(old==current,'Previously captured event or response changed')
+        existing={r[0]:r for r in original}
+        for row in rows:
+            if row[0] not in existing and name in {'tasks','workers'}:
+                value=json.loads(row[2]);ref=value.get('contextRef') if name=='tasks' else value.get('checkpoint')
+                require(isinstance(ref,dict) and isinstance(ref.get('artifact'),dict),'New delta needs verified portable cloud context/checkpoints before cutover')
+                if name=='tasks' and value.get('result'):
+                    require(isinstance(value['result'].get('checkpoint',{}).get('artifact'),dict),'New task result needs its verified cloud checkpoint')
+        tables[name]=[existing.get(row[0],row) for row in rows]
+    return tables
+
+def run(source_root,target_root,request,client=None,observe=None):
+    require(set(request)=={'documentId','datasetId','expectedCurrentVersionId','sourceDigest'},'Exact cutover selectors required')
+    from .storage import Library
+    from . import live
+    if observe is None:observe=lambda root:live.request(Library(root),'work-cutover-status',{})
+    record=source(source_root,observe);require(record['sourceDigest']==request['sourceDigest'],'Reviewed source checkpoint differs')
+    if record['format']=='topolo-closed-ledger-fence-v1':
+        require(record['request']['destinationRoot']==str(pathlib.Path(target_root).resolve()) and all(record['request'][k]==request[k] for k in ['documentId','datasetId','expectedCurrentVersionId']),'Closed ledger fence target differs')
+    binding=read_json(pathlib.Path(target_root)/'work/cloud.json')
+    require(binding['format']=='topolo-cloud-work-binding-v1' and binding['organizationId']=='org_topolo_platform' and all(binding[k]==request[k] for k in ['documentId','datasetId']),'Target cloud dataset binding differs')
+    if client is None:
+        from .topolo import Client
+        client=Client('production','org:org_topolo_platform')
+    def current():
+        response=client.action('app_topolo_docs.documents.get',{'documentId':binding['documentId'],'includeHistory':False},binding['workspaceId']);doc=response['document'];versions=[v for v in response['versions'] if v['id']==doc['currentVersionId']]
+        require(doc['id']==binding['documentId'] and doc['workspaceId']==binding['workspaceId'] and doc['organizationId']==binding['organizationId'] and len(versions)==1,'Cloud cutover identity differs')
+        return doc['currentVersionId'],json.loads(versions[0]['bodyMarkdown'])
+    version,state=current();operation={'id':record['operationId'],'method':'cloud-cutover','sourceDigest':record['sourceDigest'],'installationId':binding['installationId']}
+    journal=pathlib.Path(target_root)/'work'/('cutover-'+record['operationId']+'.json');prior=read_json(journal,{})
+    if prior:
+        require(prior['operation']==operation and prior['request']==request and prior['stateDigest']==digest(state) and state.get('operation')==operation and state.get('activated') is True,'Existing cutover write may have effects; reconcile without replay')
+        return {'state':'activated','operationId':operation['id'],'replayed':False,'alreadyApplied':True}
+    require(version==request['expectedCurrentVersionId'] and state['format']=='topolo-cloud-work-state-v1' and state['datasetId']==binding['datasetId'] and state.get('activated') is False and state['generation']==0 and set(state['tables'])==set(TABLES),'Inactive cloud capture changed; no cutover replay')
+    require(all(state['inventory'][key]==record['snapshot']['retained'][key] for key in ['count','sha256']),'Retained inventory changed; refresh its immutable cloud reference first')
+    tables=merge(state,record['snapshot'])
+    from .work_artifacts import read_checkpoint,materialize_result
+    from .topolo import read_artifact
+    import tempfile
+    old_tasks={row[0] for row in state['tables']['tasks']};old_workers={row[0] for row in state['tables']['workers']}
+    for row in tables['tasks']:
+        if row[0] not in old_tasks:
+            ref=json.loads(row[2])['contextRef']['artifact']
+            with tempfile.TemporaryDirectory(prefix='topolo-cutover-context-') as tmp:read_artifact(client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,pathlib.Path(tmp)/'context.json')
+            task=json.loads(row[2])
+            if task.get('result'):
+                with tempfile.TemporaryDirectory(prefix='topolo-cutover-result-') as tmp:materialize_result(pathlib.Path(target_root)/'work',task,pathlib.Path(tmp),client)
+    for row in tables['workers']:
+        if row[0] not in old_workers:read_checkpoint(pathlib.Path(target_root)/'work',json.loads(row[2])['checkpoint'],row[1],row[0],client=client)
+    next_state={**state,'tables':tables,'activated':True,'generation':1,'operation':operation};body=canonical(next_state).decode();require(len(body.encode())<=900000,'Cloud cutover exceeds its bounded state contract')
+    require(source(source_root,observe)==record,'Source cutover generation changed before CAS')
+    fd=os.open(journal,os.O_WRONLY|os.O_CREAT|os.O_EXCL|os.O_NOFOLLOW,0o600)
+    try:
+        os.write(fd,canonical({'operation':operation,'request':request,'stateDigest':digest(next_state)}));os.fsync(fd)
+    finally:os.close(fd)
+    sync_directory(journal.parent)
+    error=None
+    try:client.action('app_topolo_docs.documents.versions.create',{'documentId':binding['documentId'],'bodyMarkdown':body,'expectedCurrentVersionId':version},binding['workspaceId'],write=True)
+    except Exception as exc:error=exc
+    try:_,actual=current()
+    except Exception as exc:raise PackError('Cloud cutover outcome is uncertain; reconcile without repeating the write') from exc
+    if record['format']=='topolo-closed-ledger-fence-v1':
+        require(source(source_root,observe)==record,'Closed ledger ownership changed after cloud acknowledgement; reconcile without replay')
+    require(actual==next_state,'Cloud cutover was refused or changed; reconcile without repeating the write')
+    return {'state':'activated','operationId':operation['id'],'replayed':False,'alreadyApplied':False,'ackRecovered':error is not None,'sourceDigest':record['sourceDigest']}

package/agent-packs/src/topolo_agent_pack/cloud_delta.py

@@ -0,0 +1,162 @@
+"""Convert explicitly selected CLOSED legacy results, never native histories."""
+import hashlib,json,os,pathlib,sqlite3
+from .storage import canonical,read_json,atomic_json
+from .work import Store,require,TERMINAL
+from .cloud_cutover import digest,snapshot,merge
+from .work_artifacts import publish,read_checkpoint
+from .work_context import ensure
+
+def bytes_at(path,expected,root=None):
+    path=pathlib.Path(path);st=path.lstat()
+    require(path.is_file() and not path.is_symlink() and path.resolve()==path and st.st_uid==os.getuid() and st.st_nlink==1 and not st.st_mode&0o022 and 0<st.st_size<=100*1024*1024,'Declared source must be an owned immutable ordinary file')
+    require(root is None or path.is_relative_to(root),'Declared artifact is outside its worker workspace')
+    data=path.read_bytes();after=path.lstat()
+    require((st.st_dev,st.st_ino,st.st_size,st.st_mtime_ns,st.st_ctime_ns)==(after.st_dev,after.st_ino,after.st_size,after.st_mtime_ns,after.st_ctime_ns) and hashlib.sha256(data).hexdigest()==expected,'Declared source digest changed')
+    return data
+
+def checkpoint(store,task,worker):
+    require(worker['state']=='archived' and worker.get('nativeArchived') is True,'Native archival is not verified in the retained owner record')
+    proof=worker['checkpoint'];path=store.root/'checkpoints'/task['id']/(worker['id']+'.json')
+    require(set(proof)=={'path','sha256'} and proof['path']==str(path),'Exact original checkpoint binding required')
+    original=json.loads(bytes_at(path,proof['sha256']))
+    require(set(original)=={'nativeTurn','resolution','taskId','worker'} and original['taskId']==task['id'] and original['resolution']==worker['resolution'],'Original checkpoint task or resolution differs')
+    retained=original['worker'];actual=original['nativeTurn']
+    require(all(retained.get(k)==worker.get(k) for k in ['id','taskId','phase','nativeId','turnId','resolution']) and actual['id']==worker['turnId'] and actual['status']=='completed' and actual.get('error') is None,'Original terminal native receipt differs')
+    output='\n'.join(i.get('text','') for i in actual['items'] if i.get('type')=='agentMessage' and i.get('phase')!='commentary')
+    require(0<len(output.encode())<=100000,'Selected final output exceeds checkpoint boundary')
+    # Deliberately do not return nativeTurn, prompts, tool logs or reasoning.
+    return {'output':output,'receipt':{'threadId':worker['nativeId'],'turnId':worker['turnId'],'status':'completed','toolItems':sum(i.get('type') not in {'agentMessage','userMessage','reasoning','plan'} for i in actual['items']),'sourceCheckpointSHA256':proof['sha256'],'archivalRecordSHA256':digest(worker)}}
+
+def safe_artifact(data):
+    """JSON histories are never declared artifacts, even via a nested manifest."""
+    try:pending=[json.loads(data)]
+    except (ValueError,UnicodeDecodeError):
+        pending=[]
+        for line in data.splitlines():
+            try:pending.append(json.loads(line))
+            except (ValueError,UnicodeDecodeError):pass
+    while pending:
+        item=pending.pop()
+        if isinstance(item,dict):
+            require('nativeTurn' not in item and item.get('type') not in {'reasoning','userMessage','response_item','event_msg','session_meta','turn_context'} and not (isinstance(item.get('turns'),list) and item['turns']),'Raw native history cannot be published as a declared artifact')
+            pending.extend(item.values())
+        elif isinstance(item,list):pending.extend(item)
+
+def selected_artifacts(task,workers,selector):
+    """Read-only completeness qualification, before any context/artifact upload."""
+    execute=[w for w in workers if w['phase']=='execute'];require(len(execute)==1,'One exact existing execution result required')
+    worker=execute[0];cwd=pathlib.Path(worker['cwd']).resolve();declared=selector['artifactManifest']
+    checkpoints={(w['checkpoint']['path'],w['checkpoint']['sha256']) for w in workers}
+    reviewed=[{'path':r['path'],'sha256':r['sha256']} for r in task.get('verification',{}).get('evidence',[]) if (r['path'],r['sha256']) not in checkpoints]
+    external={(r['path'],r['sha256']) for r in reviewed if not pathlib.Path(r['path']).is_relative_to(cwd)}
+    if declared is not None:
+        require(set(declared)=={'path','sha256'},'Exact declared manifest reference required')
+        value=json.loads(bytes_at(declared['path'],declared['sha256']))
+        if isinstance(value,list):
+            require(pathlib.Path(declared['path']).is_relative_to(cwd),'Original list manifest must remain in its worker workspace')
+            rows=value
+        else:
+            require(isinstance(value,dict) and set(value)=={'format','taskId','workerId','artifacts'} and value['format']=='topolo-selected-task-artifacts-v1' and value['taskId']==task['id'] and value['workerId']==worker['id'],'Selected manifest task or worker identity differs')
+            rows=value['artifacts']
+    else:
+        require(not external,'External reviewed evidence requires an explicit selected artifact manifest')
+        rows=reviewed
+    require(isinstance(rows,list) and (0 if declared is None else 1)<=len(rows)<=64,'Declared artifact manifest exceeds its bound')
+    require(all(isinstance(r,dict) and {'path','sha256'}<=set(r)<= {'path','sha256','bytes','contentPath'} for r in rows),'Declared artifact fields differ')
+    require(len({r['path'] for r in rows})==len(rows),'Duplicate declared artifact')
+    selected={(r['path'],r['sha256']) for r in rows}
+    require(all((r['path'],r['sha256']) in selected for r in reviewed),'Selected manifest omits reviewed evidence')
+    require(not selected.intersection(checkpoints),'Raw native checkpoint cannot be declared as an artifact')
+    for row in rows:
+        inside=pathlib.Path(row['path']).is_relative_to(cwd)
+        require(inside or declared is not None and (row['path'],row['sha256']) in external,'External artifact lacks exact reviewed task evidence')
+        data=artifact_bytes(row,reviewed,declared,cwd);safe_artifact(data)
+        require('bytes' not in row or row['bytes']==len(data),'Declared artifact size differs')
+        if pathlib.Path(row['path'])==cwd/'TASK-CONTINUATION.json':
+            packet=json.loads(data)
+            require(isinstance(packet,dict) and packet.get('format')=='topolo-task-continuation-evidence-v1' and packet.get('taskId')==task['id'] and isinstance(packet.get('proof'),dict) and all(isinstance(value,str) for value in packet['proof'].values()),'Continuation evidence task identity differs')
+            proof_paths={value for value in packet['proof'].values() if isinstance(value,str) and pathlib.Path(value).is_absolute()}
+            require(proof_paths.issubset({r['path'] for r in rows}),'Selected manifest omits continuation proof artifacts')
+    return worker,declared,rows
+
+def artifact_bytes(row,reviewed,declared,cwd):
+    """An explicit archive may supply only the exact previously reviewed bytes.
+
+    Keep the original evidence identity; never overwrite a live owner's file or
+    relabel its current contents as the historical checkpoint.
+    """
+    content=row.get('contentPath',row['path'])
+    if 'contentPath' in row:
+        require(declared is not None and content!=row['path'] and
+            (row['path'],row['sha256']) in {(r['path'],r['sha256']) for r in reviewed},
+            'Archived content requires an explicit exact reviewed artifact')
+        require(pathlib.Path(content).is_absolute() and pathlib.Path(content).is_relative_to(pathlib.Path(declared['path']).parent),
+            'Archived content must be inside its selected manifest directory')
+        return bytes_at(content,row['sha256'])
+    return bytes_at(content,row['sha256'],cwd if pathlib.Path(row['path']).is_relative_to(cwd) else None)
+
+def artifacts(store,task,workers,selector,client):
+    worker,declared,rows=selected_artifacts(task,workers,selector);cwd=pathlib.Path(worker['cwd']).resolve();result=[]
+    reviewed=task.get('verification',{}).get('evidence',[])
+    for index,row in enumerate(rows):
+        path=pathlib.Path(row['path']);inside=path.is_relative_to(cwd)
+        data=artifact_bytes(row,reviewed,declared,cwd);safe_artifact(data)
+        ref=publish(store.root,task['id'],'legacy-'+worker['id']+'-artifact-'+str(index),data,client=client)
+        result.append({'title':str(path.relative_to(cwd)) if inside else 'Reviewed external evidence: '+path.name,'sourcePath':row['path'],'sourceSHA256':row['sha256'],**({'archivedContentPath':row['contentPath']} if 'contentPath' in row else {}),'artifact':ref})
+    manifest={'format':'topolo-task-artifact-manifest-v1','taskId':task['id'],'workerId':worker['id'],'sourceManifest':declared,'artifacts':result,'nativeHistoryIncluded':False}
+    ref=publish(store.root,task['id'],'legacy-'+worker['id']+'-artifact-manifest',canonical(manifest),client=client)
+    return {'title':'Selected task artifact manifest','artifact':ref}
+
+def run(source_root,target_root,request,client=None):
+    require(set(request)=={'documentId','datasetId','expectedCurrentVersionId','tasks'} and isinstance(request['tasks'],list) and 1<=len(request['tasks'])<=16,'Exact portable delta request required')
+    require(len({s['taskId'] for s in request['tasks']})==len(request['tasks']) and all(set(s)=={'taskId','revision','artifactManifest'} for s in request['tasks']),'Exact distinct task selectors required')
+    from .cloud_work import CloudStore
+    if client is None:
+        from .topolo import Client
+        client=Client('production','org:org_topolo_platform')
+    binding=CloudStore(target_root,client).binding
+    require(all(binding[k]==request[k] for k in ['documentId','datasetId']),'Portable delta cloud dataset differs')
+    response=client.action('app_topolo_docs.documents.get',{'documentId':binding['documentId'],'includeHistory':False},binding['workspaceId']);doc=response['document'];versions=[v for v in response['versions'] if v['id']==doc['currentVersionId']]
+    require(doc['currentVersionId']==request['expectedCurrentVersionId'] and doc['id']==binding['documentId'] and doc['workspaceId']==binding['workspaceId'] and doc['organizationId']==binding['organizationId'] and len(versions)==1,'Inactive capture generation differs')
+    state=json.loads(versions[0]['bodyMarkdown']);require(state['format']=='topolo-cloud-work-state-v1' and state['datasetId']==binding['datasetId'] and state['generation']==0 and state.get('activated') is False,'Only the existing inactive cloud capture may receive prepared delta')
+    require(not {s['taskId'] for s in request['tasks']} & {r[0] for r in state['tables']['tasks']},'Previously captured tasks must retain their cloud records')
+    store=Store(source_root);directory=store.root/'delta-preparations';directory.mkdir(mode=0o700,exist_ok=True);operation=digest(request);path=directory/(operation+'.json');record=read_json(path,{})
+    if record:
+        require(record['request']==request,'Existing portable preparation differs')
+    else:
+        tasks={};workers={}
+        with store.db() as db:
+            capture=snapshot(db);prefix={'tables':{name:[row for row in capture['tables'][name] if row[0] in {old[0] for old in state['tables'][name]}] for name in capture['tables']}}
+            merge(state,prefix)
+            for selector in request['tasks']:
+                row=db.execute('SELECT body FROM tasks WHERE id=?',(selector['taskId'],)).fetchone();require(row is not None,'Unknown selected task');task=json.loads(row[0]);owned=[json.loads(w[0]) for w in db.execute('SELECT body FROM workers WHERE task_id=? ORDER BY id',(task['id'],))]
+                require(task['revision']==selector['revision'] and task['state'] in TERMINAL and owned,'Selected task is not at its reviewed closed checkpoint')
+                for worker in owned:checkpoint(store,task,worker)
+                tasks[task['id']]=task;workers[task['id']]=owned
+        record={'format':'topolo-portable-delta-v1','request':request,'tasks':tasks,'workers':workers,'prepared':{},'applied':{}};atomic_json(path,record)
+    for selector in request['tasks']:
+        if selector['taskId'] not in record['prepared']:
+            selected_artifacts(record['tasks'][selector['taskId']],record['workers'][selector['taskId']],selector)
+    for selector in request['tasks']:
+        tid=selector['taskId'];task=record['tasks'][tid];owned=record['workers'][tid];source_digest=digest({'task':task,'workers':owned})
+        if tid not in record['prepared']:
+            context=ensure(store.root,task,client);manifest=artifacts(store,task,owned,selector,client);proofs={};result=None;verification=None
+            for worker in owned:
+                selected=checkpoint(store,task,worker);output=selected['output']
+                if worker['phase']=='execute':
+                    require(task['result']['summary']==output,'Task result differs from the original final assistant output')
+                    output=canonical({'summary':output,'artifacts':[manifest],'references':['historical-checkpoint-sha256:'+worker['checkpoint']['sha256']]}).decode()
+                elif worker['phase']=='review':
+                    review=json.loads(output);require(review['verdict']==task['verification']['verdict'] and review['summary']==task['verification']['summary'],'Task verification differs from its original terminal receipt')
+                    output=canonical({'verdict':review['verdict'],'summary':review['summary'],'evidence':[manifest]}).decode()
+                payload={'format':'topolo-task-checkpoint-v1','taskId':tid,'workerId':worker['id'],'phase':worker['phase'],'nativeReceipt':selected['receipt'],'resolution':worker['resolution'],'roleSource':worker.get('roleSource'),'contextRef':context,'output':output,'outputError':None,'nativeHistoryIncluded':False}
+                artifact=publish(store.root,tid,'legacy-'+worker['id']+'-portable-checkpoint',canonical(payload),client=client);proof={'artifact':artifact,'sha256':artifact['sha256']}
+                actual=read_checkpoint(store.root,proof,tid,worker['id'],client);require(actual==payload,'Normalized cloud checkpoint readback differs');proofs[worker['id']]=proof
+                if worker['phase']=='execute':result={**json.loads(output),'workerId':worker['id'],'checkpoint':proof}
+                elif worker['phase']=='review':verification={**json.loads(output),'nativeCheckpoint':proof,'historicalEvidence':task['verification'].get('evidence',[])}
+            require(result is not None and verification is not None,'Original execution and review checkpoints are required')
+            record['prepared'][tid]={'workers':proofs,'changes':{'contextRef':context,'result':result,'verification':verification}};atomic_json(path,record)
+        prepared=record['prepared'][tid]
+        actual=store.portable_delta(tid,selector['revision'],source_digest,prepared['workers'],prepared['changes'],operation)
+        record['applied'][tid]={'revision':actual['revision'],'sourceDigest':source_digest};atomic_json(path,record)
+    return {'state':'portable-delta-prepared','operationId':operation,'tasks':record['applied'],'tasksCreated':0,'nativeRunsStarted':0,'cloudTaskStateChanged':False}

package/agent-packs/src/topolo_agent_pack/cloud_migrate.py

@@ -0,0 +1,142 @@
+"""Attach a durably fenced, idle Codex installation to its existing cloud dataset.
+
+Only installation metadata changes. The legacy ledger remains permanently fenced;
+cloud task rows and their owners are never written or adopted by this operation.
+"""
+import copy,hashlib,json,pathlib,re,sqlite3,types
+from .storage import Library,read_json,atomic_json,canonical,sync_directory
+from .work import require
+from .cloud_work import CloudStore
+from .cloud_cutover import digest,snapshot
+from . import closed_ledger_fence as fence,native,permissions
+from .domain_context import references
+
+FORMAT='topolo-existing-cloud-migration-v1'
+FIELDS={'installationId','expectedFenceDigest','expectedMetadataDigest','expectedTargetCatalogDigest'}
+
+def metadata(lib):
+    active=read_json(lib.root/'active.json');runtime=pathlib.Path(active['runtime'])
+    require(runtime.is_relative_to(lib.root/'runtimes') and runtime.resolve()==runtime,'Original runtime identity differs')
+    saved=read_json(lib.root/'work/config.json');packs={saved['pack'],*(c['pack'] for c in saved.get('channels',{}).values())}
+    files={name:read_json(lib.root/name) for name in ['active.json','work/config.json','work/role-bindings.json','work/context-authority.json']}
+    execution=read_json(runtime/'execution-policy.json');keys={c['key'] for c in active['components']}
+    selected=[{k:v for k,v in r.items() if k!='organizationPolicyProof'} for r in execution['roles'] if r['key'] in keys]
+    require(len(selected)==len(keys),'Original coordinator policy is ambiguous or missing')
+    # Task worker roles are appended/retired by the broker. Pin the original
+    # coordinator authority without treating authorized workers as policy drift.
+    files[str(runtime.relative_to(lib.root)/'execution-policy.json')]={k:v for k,v in execution.items() if k not in {'roles','applied','modelTurnsStarted'}}|{'roles':selected}
+    for pack in sorted(packs):
+        manifest,revision=lib.load(pack);files['manifest:'+pack]={'manifest':manifest,'revision':revision}
+        files['permissions/'+pack+'.json']=read_json(lib.root/'permissions'/(pack+'.json'))
+        files['dynamic-models/'+pack+'.json']=read_json(lib.root/'dynamic-models'/(pack+'.json'))
+    for name in files:
+        if not name.startswith('manifest:'):fence.owned(lib.root/name)
+    return files
+
+def source(lib):
+    root=lib.root.resolve();work=root/'work';require(not (root/'live-bridge.json').exists() and not lib.pending(),'Original native owner must be stopped with no pending operation')
+    active=lib.active();native.assert_idle(pathlib.Path(active['runtime'])/'home')
+    record=read_json(work/'cutover.json');require(record.get('format')==fence.CAPABILITY and record.get('state')=='ledger-fenced' and record.get('root')==str(root),'Exact closed legacy fence required')
+    ident=fence.identity(root);require(ident==record['databaseIdentity'] and fence.code_digest()==record['codeDigest'],'Original fenced ledger ownership or guard changed')
+    fence.owned(work/'cutover.json')
+    from contextlib import closing
+    with closing(sqlite3.connect('file:'+str(work/'tasks.sqlite')+'?mode=ro',uri=True)) as db:
+        db.execute('BEGIN');rows=db.execute('SELECT operation_id,body FROM '+fence.META).fetchall()
+        require(len(rows)==1 and rows[0][0]==record['operationId'] and json.loads(rows[0][1])==record,'Immutable legacy fence receipt differs')
+        require(fence.schema(db,True)==record['schemaDigest'] and digest(snapshot(db))==record['sourceDigest']==digest(record['snapshot']),'Fenced legacy history changed')
+    require(fence.identity(root)==ident,'Legacy ledger identity changed during observation')
+    target=pathlib.Path(record['request']['destinationRoot']);fence.owned(target,True);fence.owned(target/'work/cloud.json')
+    binding=read_json(target/'work/cloud.json');require(digest(binding)==record['targetBindingDigest'],'Original target authority changed')
+    return record,target,binding
+
+def verified(root):
+    """Every admission rechecks the exact installed metadata closure, never a flag."""
+    lib=Library(root)
+    record=read_json(lib.root/'work/cloud-migration.json',{})
+    require(record.get('format')==FORMAT and record.get('state')=='verified','Existing cloud migration is incomplete; reconcile before dispatch')
+    from .coordinator_refresh import effective
+    metadata_digest,catalog_digest=effective(lib,record)
+    require(digest(metadata(lib))==metadata_digest and read_json(lib.root/'work/cloud.json')==record['binding'] and digest(read_json(lib.root/'work/cutover.json'))==record['fenceDigest'],'Reviewed cloud migration metadata or authority changed')
+    require(record.get('preserveOtherInstallationOwnership') is True,'Cross-installation ownership must remain unchanged')
+    cutover=read_json(lib.root/'work/cutover.json');target=pathlib.Path(cutover['request']['destinationRoot'])
+    catalog=read_json(target/'work/role-catalog.json');registry=read_json(lib.root/'work/role-bindings.json')
+    require(digest(catalog)==catalog_digest,'Reviewed canonical specialization catalog changed')
+    by_logical={v['logicalId']:k for k,v in registry['roles'].items()}
+    selected={c:[by_logical[catalog['bindings'][k]['logicalId']] for k in catalog['channels'][c]['roleKeys']] for c in ['engineering','operations','cicd']}
+    require(selected==record['channelRoleKeys'],'Reviewed channel specialization closure changed')
+    return record
+
+def plan(lib,request,client=None):
+    require(isinstance(request,dict) and set(request)==FIELDS and all(isinstance(v,str) and 1<=len(v)<=240 for v in request.values()) and re.fullmatch('[a-z0-9][a-z0-9-]{0,119}',request['installationId']),'Exact existing cloud migration selectors required')
+    require(not (lib.root/'work/cloud-migration.json').exists() and not (lib.root/'work/cloud.json').exists(),'Existing migration must be reconciled without replay')
+    record,target,binding=source(lib);before=metadata(lib)
+    require(digest(record)==request['expectedFenceDigest'] and digest(before)==request['expectedMetadataDigest'],'Reviewed original installation changed')
+    require(request['installationId']!=binding['installationId'],'A separate installation identity is required')
+    for name in ['role-catalog.json','role-bindings.json','config.json']:fence.owned(target/'work'/name)
+    target_catalog=read_json(target/'work/role-catalog.json');target_refs=read_json(target/'work/role-bindings.json')
+    target_config=read_json(target/'work/config.json')
+    require(digest(target_catalog)==request['expectedTargetCatalogDigest']==target_config['catalogDigest'] and target_refs['roles']==target_catalog['bindings'],'Reviewed target role catalog differs')
+    if client is None:
+        from .topolo import Client
+        client=Client('production','org:org_topolo_platform')
+    require(client.environment=='production' and client.context=='org:org_topolo_platform','Production organization context required')
+    actor=client.run(['whoami']);require(actor['organization']['id']=='org_topolo_platform','Current cloud organization differs')
+    for key,value in before.items():
+        if not key.startswith('manifest:'):continue
+        manifest=value['manifest'];pack=manifest['packId'];consent=permissions.load(lib,pack,manifest['agents'])
+        require(consent and consent['sourceRevision']==value['revision'] and consent['principalId']==actor['user']['id'] and consent['contextKey']==client.context,'Original reviewed installation consent differs')
+        from .topolo import organization_execution_policy
+        _,proof=organization_execution_policy(client,consent,manifest['agents'],consent.get('agentWorkspaceId'));permissions.authorize_native_scope(proof)
+    registry=before['work/role-bindings.json'];logical={r['logicalId']:r for r in target_refs['roles'].values()}
+    require(len(logical)==len(target_refs['roles'])==len(registry['roles']),'Canonical role identity inventory differs')
+    updated=copy.deepcopy(registry)
+    by_logical={v['logicalId']:k for k,v in registry['roles'].items()}
+    channel_roles={c:[by_logical[target_refs['roles'][k]['logicalId']] for k in target_catalog['channels'][c]['roleKeys']] for c in ['engineering','operations','cicd']}
+    for key,old in registry['roles'].items():
+        ref=logical.get(old['logicalId']);require(ref and all(old[k]==ref[k] for k in ['agentId','workspaceId','logicalId']),'Existing role identity cannot be replaced')
+        updated['roles'][key]=copy.deepcopy(ref)
+    # Live read-back is limited to changed role definitions; unchanged references
+    # are still pinned to the reviewed canonical catalog and checked at dispatch.
+    changed={k:v for k,v in updated['roles'].items() if v!=registry['roles'][k]}
+    require(all(v['logicalId']=='intakes/cicd' or v['logicalId'] in {'specialists/'+x for x in ['queue-recovery','runner-capacity','pipeline-engineering','promotion-deployment','release-verification']} for v in changed.values()),'Unexpected specialist definition change')
+    for ref in changed.values():
+        agent=client.action('app_topolo_agent.agents.get',{'id':ref['agentId']},ref['workspaceId'])['agent'];config=json.loads(agent['config']) if isinstance(agent['config'],str) else agent['config'];spec=config['specialization']
+        require(agent['id']==ref['agentId'] and agent['workspaceId']==ref['workspaceId'] and agent['organizationId']=='org_topolo_platform' and spec['format']=='topolo-role-specialization-v1' and spec['logicalId']==ref['logicalId'] and config['purpose']==spec['instructions'] and hashlib.sha256(spec['instructions'].encode()).hexdigest()==ref['instructionsSHA256'] and references(config,ref['logicalId'])==ref.get('domainContextRefs',[]),'Reviewed live role definition differs')
+    version,state=CloudStore.load(types.SimpleNamespace(binding=binding,client=client))
+    require(state['inventory']['count']==record['snapshot']['retained']['count'] and state['inventory']['sha256']==record['snapshot']['retained']['sha256'],'Current canonical dataset or retained inventory changed')
+    for name in ['tasks','workers']:
+        cloud={r[0]:r for r in state['tables'][name]}
+        for old in record['snapshot']['tables'][name]:require(old[0] in cloud and cloud[old[0]][1]==old[1],'Original task or worker identity is missing from cloud')
+        for row in cloud.values():
+            body=json.loads(row[2]);require(request['installationId'] not in [body.get('ownerInstallationId'),body.get('installationId'),body.get('nativePlan',{}).get('installationId')],'New installation identity already owns work')
+    saved=before['work/config.json'];require(set(saved) in [{'pack','revision','templateRuntime','maxWorkers','channels'},{'pack','revision','templateRuntime','maxWorkers','channels','frontdoorDispatch'}],'Exact existing legacy channel configuration required')
+    require('authority' not in saved and saved.get('frontdoorDispatch') in {None,False},'Original legacy task configuration differs')
+    after={**before,'work/config.json':{**saved,'authority':'topolo-docs','frontdoorDispatch':True},'work/role-bindings.json':updated}
+    roles=next(v['roles'] for k,v in before.items() if k.endswith('/execution-policy.json'))
+    keys={channel:(saved.get('channels',{}).get(channel,{}).get('pack',saved['pack'])+'/intakes/'+intake) for channel,intake in [('engineering','engineering'),('operations','operator-01'),('cicd','cicd')]}
+    native_keys={r['key']:r['threadId'] for r in roles};components={c['key']:c['threadId'] for c in before['active.json']['components']}
+    require(set(components)==set(keys.values()) and all(native_keys.get(k)==components.get(k) and components.get(k) for k in keys.values()),'Original three native coordinators differ')
+    for channel,key in keys.items():
+        pack=key.split('/')[0];manifest=before['manifest:'+pack]
+        require(set(channel_roles[channel])<={a['pack']+'/'+a['set']+'/'+a['id'] for a in manifest['manifest']['agents']} and before['dynamic-models/'+pack+'.json']['sourceRevision']==manifest['revision'],'Reviewed native channel templates or task model policy differ')
+    require(metadata(lib)==before and source(lib)[0]==record and read_json(target/'work/role-catalog.json')==target_catalog and read_json(target/'work/role-bindings.json')==target_refs and read_json(target/'work/config.json')==target_config,'Installation or canonical role source changed during planning')
+    return {'format':FORMAT,'preserveOtherInstallationOwnership':True,'request':request,'fenceDigest':digest(record),'cloudVersionId':version,'cloudDigest':digest(state),'binding':{**binding,'installationId':request['installationId']},'channelRoleKeys':channel_roles,'nativeCoordinators':{c:{'key':k,'threadId':components[k]} for c,k in keys.items()},'beforeMetadataDigest':digest(before),'afterMetadataDigest':digest(after),'before':before,'after':after,'changedRoles':sorted(changed),'cloudTaskOwners':{row[0]:json.loads(row[2]).get('ownerInstallationId') for row in state['tables']['tasks']},'taskCount':len(state['tables']['tasks']),'retainedCount':state['inventory']['count']}
+
+def apply(lib,reviewed,client=None):
+    with lib.lock():
+        current=plan(lib,reviewed['request'],client)
+        # Cloud state is observed, never written by attachment. Its ordinary
+        # concurrent progress cannot invalidate an unchanged local effect plan.
+        diagnostics={'cloudVersionId','cloudDigest','cloudTaskOwners','taskCount'}
+        require({k:v for k,v in current.items() if k not in diagnostics}=={k:v for k,v in reviewed.items() if k not in diagnostics},'Reviewed migration local preimage or immutable authority changed')
+        root=lib.root/'work';record={**current,'reviewedCloudObservation':{k:reviewed[k] for k in diagnostics},'state':'prepared'}
+        with (root/'cloud-migration.json').open('x',encoding='utf8') as stream:
+            import os
+            os.chmod(stream.name,0o600);stream.write(canonical(record).decode());stream.flush();os.fsync(stream.fileno())
+        sync_directory(root)
+        atomic_json(root/'role-bindings.json',reviewed['after']['work/role-bindings.json'])
+        atomic_json(root/'config.json',reviewed['after']['work/config.json'])
+        atomic_json(root/'cloud.json',reviewed['binding'])
+        require(digest(metadata(lib))==reviewed['afterMetadataDigest'],'Migrated metadata read-back differs')
+        atomic_json(root/'cloud-migration.json',{**record,'state':'verified'});verified(lib.root)
+        return {'state':'existing-cloud-authority-attached','installationId':reviewed['binding']['installationId'],'tasksCreated':0,'workersAdopted':0,'cloudTaskStateChanged':False,'nativeCoordinatorsPreserved':reviewed['nativeCoordinators']}

package/agent-packs/src/topolo_agent_pack/cloud_recovery.py

@@ -0,0 +1,42 @@
+"""Restore verified evidence from Bytes into a fresh, non-executing directory.
+
+The reference is portable, contains no credential or chat history, and does not
+grant a new machine ownership of running workers or permission to replay tasks.
+"""
+import gzip,hashlib,json,pathlib,tempfile
+from .storage import atomic_json
+from .work import require
+
+def recover(reference,destination,client=None):
+    require(set(reference)=={'format','organizationId','artifact','uncompressedSHA256'},'Invalid cloud recovery reference')
+    require(reference['format']=='topolo-work-recovery-v1' and reference['organizationId']=='org_topolo_platform','Cloud recovery identity differs')
+    target=pathlib.Path(destination)
+    require(not target.exists() and not target.is_symlink(),'Recovery destination must be genuinely new')
+    if client is None:
+        from .topolo import Client
+        client=Client('production','org:org_topolo_platform')
+    from .topolo import read_artifact
+    ref=reference['artifact']
+    with tempfile.TemporaryDirectory(prefix='topolo-cloud-recovery-') as tmp:
+        archive=pathlib.Path(tmp)/'archive.gz'
+        read_artifact(client,{'input':{'bytesScope':ref['scope'],'bytesWorkspaceId':ref['workspaceId']}},ref['key'],ref,archive)
+        with gzip.open(archive,'rb') as stream:raw=stream.read(100*1024*1024+1)
+        require(len(raw)<=100*1024*1024,'Recovery archive exceeds decompression boundary')
+    require(hashlib.sha256(raw).hexdigest()==reference['uncompressedSHA256'],'Recovery archive digest differs')
+    bundle=json.loads(raw)
+    require(bundle['format']=='topolo-work-migration-evidence-v1' and bundle['executionAuthorized'] is False and bundle['nativeChatHistoryIncluded'] is False,'Recovery archive is not a qualified evidence snapshot')
+    files={}
+    for original,entry in bundle['files'].items():
+        data=entry['text'].encode()
+        require(hashlib.sha256(data).hexdigest()==entry['sha256'],'Recovered file digest differs')
+        # Never restore the original absolute path, follow links, or execute it.
+        files[original]={'sha256':entry['sha256'],'cachePath':'objects/'+entry['sha256']}
+    target.mkdir(parents=True,mode=0o700)
+    (target/'objects').mkdir(mode=0o700)
+    for original,entry in bundle['files'].items():
+        path=target/files[original]['cachePath']
+        if not path.exists():path.write_bytes(entry['text'].encode());path.chmod(0o600)
+    atomic_json(target/'task-state.json',bundle['taskState'])
+    result={'format':'topolo-work-recovery-receipt-v1','authority':'verified-cloud-evidence-snapshot','executionAuthorized':False,'nativeChatHistoryIncluded':False,'files':files,'missing':bundle['missing'],'taskIds':[r[0] for r in bundle['taskState']['tasks']],'workerIds':[r[0] for r in bundle['taskState']['workers']],'tasksCreated':0,'workersAdopted':0,'reference':reference}
+    atomic_json(target/'recovery.json',result)
+    return result