@atmem/architect 0.0.0-stage → 0.2.0

package/src/runtime/invoice_object_store.py

@@ -0,0 +1,153 @@
+"""Private immutable invoice objects with native conditional writes/version reads.
+
+Account identity comes from the verified application membership, never an object
+URL or a model. Adapters use operator-owned destinations/workload credentials.
+Cloud IAM, versioning, retention and residency require matching infrastructure.
+"""
+import base64
+from email.utils import formatdate
+import hashlib
+import json
+import re
+import time
+import threading
+import uuid
+from urllib.parse import quote
+import requests
+
+LIMIT=10000000
+FIELDS={'provider','region','bucket','key','version','sha256'}
+class ObjectUnavailable(RuntimeError):pass
+
+def digest_pdf(raw):
+    if not isinstance(raw,bytes)or not raw.startswith(b'%PDF-')or len(raw)>LIMIT:raise ValueError('Supply a PDF no larger than 10 MB')
+    return hashlib.sha256(raw).hexdigest()
+
+def object_key(account_id,digest):
+    if not isinstance(account_id,str)or str(uuid.UUID(account_id))!=account_id:raise ValueError('Use the verified canonical account identity')
+    if not isinstance(digest,str)or not re.fullmatch(r'[0-9a-f]{64}',digest):raise ValueError('Invalid invoice content digest')
+    return'accounts/'+account_id+'/invoices/'+digest+'.pdf'
+
+class InvoiceObjects:
+    def _reference(self,account_id,digest,version):
+        if not isinstance(version,str)or not 1<=len(version)<=1024 or version=='null'or any(ord(c)<33 or ord(c)>126 for c in version):raise ObjectUnavailable('A native immutable object version is required')
+        if self.provider=='gcp'and not re.fullmatch(r'[1-9][0-9]{0,29}',version):raise ObjectUnavailable('Invalid native object generation')
+        return {'provider':self.provider,'region':self.region,'bucket':self.bucket,'key':object_key(account_id,digest),'version':version,'sha256':digest}
+    def _check(self,account_id,reference):
+        if not isinstance(reference,dict)or set(reference)!=FIELDS:raise ValueError('Use the exact owned object reference')
+        expected=self._reference(account_id,reference['sha256'],reference['version'])
+        if reference!=expected:raise PermissionError('Object reference is outside the account/destination boundary')
+        return expected
+    def _content(self,raw,reference):
+        if digest_pdf(raw)!=reference['sha256']:raise ObjectUnavailable('Original invoice digest changed')
+        return raw
+
+class HttpInvoiceObjects(InvoiceObjects):
+    def __init__(self,provider,region,bucket,authorization,*,account=None,session=None):
+        if not isinstance(bucket,str)or not re.fullmatch(r'[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]',bucket)or'..'in bucket:raise ValueError('Invalid private document destination')
+        if not callable(authorization):raise ValueError('Explicit workload identity is required')
+        if not isinstance(region,str)or not re.fullmatch(r'[a-z][a-z0-9-]{1,40}',region):raise ValueError('Invalid document region')
+        self.provider=provider;self.region=region;self.bucket=bucket;self.authorization=authorization;self.session=session or requests.Session();self.session.trust_env=False
+        if provider=='azure':
+            if not isinstance(account,str)or not re.fullmatch(r'[a-z0-9]{3,24}',account)or'.'in bucket:raise ValueError('Invalid private Azure storage destination')
+            self.origin='https://'+account+'.blob.core.windows.net/'+bucket+'/'
+        elif provider=='ibm':
+            if not re.fullmatch(r'[a-z]{2}-[a-z]+',region):raise ValueError('Use an explicit regional IBM object destination')
+            self.origin='https://s3.'+region+'.cloud-object-storage.appdomain.cloud/'+bucket+'/'
+        elif provider=='gcp':
+            self.origin='https://storage.googleapis.com/storage/v1/b/'+bucket+'/o/'
+            self.upload='https://storage.googleapis.com/upload/storage/v1/b/'+bucket+'/o'
+        else:raise ValueError('Unsupported native private object adapter')
+    def _headers(self):
+        supplied=self.authorization();auth=supplied.get('Authorization')if isinstance(supplied,dict)else None
+        if not isinstance(auth,str)or not auth.startswith('Bearer ')or not 8<=len(auth)<=20000 or any(ord(c)<33 or ord(c)>126 for c in auth[7:]):raise PermissionError('Private object workload identity unavailable')
+        headers={'Authorization':auth,'Content-Type':'application/pdf'}
+        if self.provider=='azure':headers.update({'x-ms-version':'2023-11-03','x-ms-date':formatdate(usegmt=True)})
+        return headers
+    def _send(self,method,url,*,headers=None,params=None,data=None,limit=LIMIT):
+        actual={**self._headers(),**(headers or {})};deadline=time.monotonic()+15
+        try:
+            with self.session.request(method,url,headers=actual,params=params,data=data,timeout=(2,8),allow_redirects=False,stream=True)as response:
+                code=response.status_code
+                if code in {401,403}:raise PermissionError('Private object access denied')
+                if code in {409,412}:return code,b'',{}
+                if code not in {200,201}:raise ObjectUnavailable('Private object operation unavailable')
+                raw=bytearray()
+                for chunk in response.iter_content(16384):
+                    raw.extend(chunk)
+                    if len(raw)>limit or time.monotonic()>deadline:raise ObjectUnavailable('Private object response exceeded its boundary')
+                return code,bytes(raw),{key.lower():value for key,value in response.headers.items()}
+        except(PermissionError,ObjectUnavailable):raise
+        except Exception:raise ObjectUnavailable('Private object operation unavailable')from None
+    def _version(self,raw,headers):
+        if self.provider=='gcp':
+            try:
+                def unique(pairs):
+                    result={}
+                    for key,value in pairs:
+                        if key in result:raise ValueError('Duplicate metadata field')
+                        result[key]=value
+                    return result
+                return json.loads(raw,object_pairs_hook=unique)['generation']
+            except(ValueError,TypeError,KeyError):raise ObjectUnavailable('Native object generation unavailable')from None
+        return headers.get('x-ms-version-id'if self.provider=='azure'else'x-amz-version-id')
+    def put(self,account_id,raw):
+        digest=digest_pdf(raw);key=object_key(account_id,digest)
+        if self.provider=='gcp':
+            code,body,headers=self._send('POST',self.upload,params={'uploadType':'media','name':key,'ifGenerationMatch':'0','fields':'generation'},data=raw,limit=8192)
+        else:
+            extra={'If-None-Match':'*','Content-MD5':base64.b64encode(hashlib.md5(raw,usedforsecurity=False).digest()).decode()}
+            if self.provider=='azure':extra['x-ms-blob-type']='BlockBlob'
+            code,body,headers=self._send('PUT',self.origin+quote(key,safe='/'),headers=extra,data=raw,limit=8192)
+        if code in {409,412}:
+            # A repeated delivery or lost upload acknowledgement must resolve the
+            # exact existing content/version, never overwrite it or guess a token.
+            if self.provider=='gcp':_,body,headers=self._send('GET',self.origin+quote(key,safe=''),params={'fields':'generation'},limit=8192)
+            else:_,body,headers=self._send('GET',self.origin+quote(key,safe='/'))
+        reference=self._reference(account_id,digest,self._version(body,headers))
+        # Re-read the pinned native version, including after a conflict. This
+        # also verifies missing versioning and mismatched object bytes fail closed.
+        self.load(account_id,reference)
+        return reference
+    def load(self,account_id,reference):
+        ref=self._check(account_id,reference);key=ref['key'];version=ref['version']
+        if self.provider=='gcp':url=self.origin+quote(key,safe='');params={'alt':'media','generation':version}
+        else:url=self.origin+quote(key,safe='/');params={'versionid'if self.provider=='azure'else'versionId':version}
+        code,raw,headers=self._send('GET',url,params=params)
+        if code!=200:raise ObjectUnavailable('Pinned original invoice unavailable')
+        version_header='x-goog-generation'if self.provider=='gcp'else'x-ms-version-id'if self.provider=='azure'else'x-amz-version-id'
+        if headers.get(version_header)!=version:raise ObjectUnavailable('Native original version mismatch')
+        return self._content(raw,ref)
+
+class S3InvoiceObjects(InvoiceObjects):
+    def __init__(self,bucket,region,owner_account_id,*,client=None):
+        if not isinstance(bucket,str)or not re.fullmatch(r'[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]',bucket)or'..'in bucket or not isinstance(region,str)or not re.fullmatch(r'[a-z]{2}-[a-z]+-[0-9]',region)or not isinstance(owner_account_id,str)or not re.fullmatch(r'\d{12}',owner_account_id):raise ValueError('Invalid owned regional S3 invoice destination')
+        self.provider='aws';self.bucket=bucket;self.region=region;self.owner_account_id=owner_account_id;self.client=client;self._client_lock=threading.Lock()
+    def _client(self):
+        if self.client is None:
+            with self._client_lock:
+                if self.client is None:
+                    import boto3
+                    from botocore.config import Config
+                    # A Session/client must not be constructed through boto3's
+                    # shared default Session concurrently by first uploads.
+                    self.client=boto3.Session().client('s3',region_name=self.region,endpoint_url='https://s3.'+self.region+'.amazonaws.com',config=Config(proxies={},connect_timeout=2,read_timeout=8,retries={'total_max_attempts':1}))
+        return self.client
+    def put(self,account_id,raw):
+        digest=digest_pdf(raw);key=object_key(account_id,digest);client=self._client()
+        try:reply=client.put_object(Bucket=self.bucket,Key=key,Body=raw,ContentType='application/pdf',ChecksumSHA256=base64.b64encode(hashlib.sha256(raw).digest()).decode(),ExpectedBucketOwner=self.owner_account_id,IfNoneMatch='*')
+        except Exception as error:
+            code=getattr(error,'response',{}).get('Error',{}).get('Code')
+            if code not in {'PreconditionFailed','ConditionalRequestConflict','412','409'}:raise ObjectUnavailable('Private object upload unavailable')from None
+            try:reply=client.head_object(Bucket=self.bucket,Key=key,ExpectedBucketOwner=self.owner_account_id)
+            except Exception:raise ObjectUnavailable('Existing original invoice unavailable')from None
+        reference=self._reference(account_id,digest,reply.get('VersionId'));self.load(account_id,reference);return reference
+    def load(self,account_id,reference):
+        ref=self._check(account_id,reference)
+        try:
+            reply=self._client().get_object(Bucket=self.bucket,Key=ref['key'],VersionId=ref['version'],ExpectedBucketOwner=self.owner_account_id);stream=reply['Body']
+            try:raw=stream.read(LIMIT+1)
+            finally:stream.close()
+        except Exception:raise ObjectUnavailable('Pinned original invoice unavailable')from None
+        if reply.get('VersionId')!=ref['version']:raise ObjectUnavailable('Native original version mismatch')
+        return self._content(raw,ref)

package/src/runtime/invoice_operations.py

@@ -0,0 +1,108 @@
+"""Separate operator authority for retention, recovery and staff membership.
+
+Never import this module into an HTTP handler. Runtime SQL logins cannot perform
+these operations. Restore/reconciliation require paused, isolated workloads.
+Expired-only cleanup serializes table mutation and refuses live jobs/leases;
+ordinary active and younger operations are preserved during online maintenance.
+All calls require an explicit transaction; receipts contain counts, not documents.
+"""
+import hashlib
+from pathlib import Path
+import re
+import uuid
+from psycopg.rows import tuple_row
+from psycopg.types.json import Jsonb
+from durable_workflow import canonical
+from workflow_database import SCHEMA_VERSION
+
+def owned_scope(conn,account_id,namespace):
+    if conn.autocommit:raise ValueError('Use one operator transaction')
+    if not isinstance(account_id,str)or str(uuid.UUID(account_id))!=account_id:raise ValueError('Use the owned canonical account UUID')
+    if not isinstance(namespace,str)or not re.fullmatch(r'[a-zA-Z0-9-]{1,20}',namespace):raise ValueError('Use the owned workflow namespace')
+    with conn.cursor(row_factory=tuple_row)as cur:
+        authority=cur.execute("SELECT pg_has_role(current_user,nspowner,'USAGE') FROM pg_namespace WHERE nspname='workflow'").fetchone()
+        version=cur.execute('SELECT version,source_sha256,queue_version FROM workflow.schema_version').fetchone()
+    expected=hashlib.sha256((Path(__file__).parent/'workflow_schema.sql').read_bytes()).hexdigest()
+    if not authority or authority[0]is not True:raise PermissionError('Use the separate reviewed schema-owner/operator connection')
+    if version!=(SCHEMA_VERSION,expected,'3.10.0'):raise ValueError('Review the schema migration before operating this database')
+    conn.execute('SET LOCAL search_path=pg_catalog,workflow,pg_temp')
+    conn.execute("SET LOCAL lock_timeout='3s'");conn.execute("SET LOCAL statement_timeout='30s'")
+    conn.execute('SELECT pg_advisory_xact_lock(hashtextextended(%s,0))',('atmem-invoice-operations:'+account_id+':'+namespace,))
+    return namespace+'.extract',namespace+'.dispatch'
+
+def quiescent_rows(conn,account_id,namespace,*,expired=False,restoring=False,limit=500):
+    extract,dispatch=owned_scope(conn,account_id,namespace)
+    if type(limit)is not int or not 1<=limit<=500:raise ValueError('Use a bounded maintenance batch')
+    # One table-lock order for every operator action. A running task retains a
+    # doing queue row even while its external network request is outside SQL.
+    conn.execute('LOCK TABLE workflow.operations IN SHARE ROW EXCLUSIVE MODE')
+    conn.execute('LOCK TABLE workflow.procrastinate_jobs IN SHARE ROW EXCLUSIVE MODE')
+    with conn.cursor(row_factory=tuple_row)as cur:
+        restoration_filter=" AND(state IN('approved','dispatching','processing')OR EXISTS(SELECT 1 FROM workflow.procrastinate_jobs j WHERE j.task_name=ANY(%s)AND j.args->>'operation_id'=workflow.operations.id::text))"if restoring else''
+        rows=cur.execute("SELECT id FROM workflow.operations WHERE account_id=%s AND workflow_key=%s"+(" AND created_at <= clock_timestamp()-interval '90 days'"if expired else'')+restoration_filter+' ORDER BY created_at,id LIMIT %s FOR UPDATE',(account_id,extract,*([[extract,dispatch]]if restoring else[]),limit)).fetchall()
+        ids=[str(row[0])for row in rows]
+        if ids:
+            live=cur.execute("SELECT EXISTS(SELECT 1 FROM workflow.procrastinate_jobs WHERE task_name=ANY(%s)AND args->>'operation_id'=ANY(%s)AND status='doing')OR EXISTS(SELECT 1 FROM workflow.operations WHERE id::text=ANY(%s)AND lease_until>clock_timestamp())",([extract,dispatch],ids,ids)).fetchone()[0]
+            if live and not restoring:raise ValueError('Settle live execution jobs/leases before expired-record maintenance')
+    return ids,extract,dispatch
+
+def purge_expired(conn,*,account_id,namespace='invoice',limit=500):
+    ids,extract,dispatch=quiescent_rows(conn,account_id,namespace,expired=True,limit=limit)
+    if ids:
+        # Only owned task identities and exact operation IDs. Queue event rows
+        # cascade through the native library schema; no global queue truncation.
+        conn.execute("DELETE FROM workflow.procrastinate_jobs WHERE task_name=ANY(%s)AND args->>'operation_id'=ANY(%s)",([extract,dispatch],ids))
+        for table in ['events','results_history','operations']:
+            column='id'if table=='operations'else'operation_id'
+            conn.execute('DELETE FROM workflow.'+table+' WHERE account_id=%s AND '+column+'::text=ANY(%s)',(account_id,ids))
+    return{'purgedOperations':len(ids),'retentionDays':90,'batchLimit':limit,'moreMayRemain':len(ids)==limit,'originalObjects':'Native private-store lifecycle; provider deletion is asynchronous. No object-read or deletion authority is conferred on this SQL tool.'}
+
+def quarantine_restored_deliveries(conn,*,account_id,workloads_stopped,namespace='invoice',limit=500):
+    # This explicit assertion is operator authorization, not a software proof
+    # that a cloud workload is stopped. Run only against the isolated restored
+    # database before changing application endpoints or starting any worker.
+    if workloads_stopped is not True:raise ValueError('Confirm workloads are stopped and the restored database is isolated')
+    ids,extract,dispatch=quiescent_rows(conn,account_id,namespace,restoring=True,limit=limit)
+    if not ids:return{'quarantinedDeliveries':0,'resetExtractions':0,'batchLimit':limit,'moreMayRemain':False}
+    # Keep payload and approval hashes. A restored database cannot know what the
+    # destination accepted after its recovery point; never infer no side effect.
+    with conn.cursor(row_factory=tuple_row)as cur:
+        rows=cur.execute("UPDATE workflow.operations SET state='unknown',lease_token=NULL,lease_until=NULL,execution_epoch=execution_epoch+1,updated_at=clock_timestamp() WHERE account_id=%s AND id::text=ANY(%s)AND state IN('approved','dispatching') RETURNING id,approved_hash",(account_id,ids)).fetchall()
+    for operation,digest in rows:
+        conn.execute("INSERT INTO workflow.events(operation_id,account_id,event,actor,detail)VALUES(%s,%s,'outcome_unknown','operator:restore',%s)",(operation,account_id,Jsonb({'reason':'database_restored','payloadSha256':digest})))
+    with conn.cursor(row_factory=tuple_row)as cur:
+        processing=cur.execute("UPDATE workflow.operations SET state='pending',lease_token=NULL,lease_until=NULL,execution_epoch=execution_epoch+1,updated_at=clock_timestamp() WHERE account_id=%s AND id::text=ANY(%s)AND state='processing' RETURNING id",(account_id,ids)).fetchall()
+    for operation, in processing:
+        conn.execute("INSERT INTO workflow.events(operation_id,account_id,event,actor,detail)VALUES(%s,%s,'recovered','operator:restore',%s)",(operation,account_id,Jsonb({'reason':'restored_extraction_fenced'})))
+    # All restored notifications may carry stale native doing/worker state.
+    # Pending extraction intent is reconstructed by reconcile_notifications after
+    # expiry cleanup. Unknown delivery intent is never automatically requeued.
+    conn.execute("DELETE FROM workflow.procrastinate_jobs WHERE task_name=ANY(%s)AND args->>'operation_id'=ANY(%s)",([extract,dispatch],ids))
+    return{'quarantinedDeliveries':len(rows),'resetExtractions':len(processing),'batchLimit':limit,'moreMayRemain':len(ids)==limit}
+
+def reconcile_completed(conn,*,account_id,operation_id,payload_sha256,external_id,operator,namespace='invoice'):
+    extract,dispatch=owned_scope(conn,account_id,namespace)
+    if not isinstance(operation_id,str)or str(uuid.UUID(operation_id))!=operation_id:raise ValueError('Use the exact operation identity')
+    if not isinstance(payload_sha256,str)or not re.fullmatch(r'[0-9a-f]{64}',payload_sha256):raise ValueError('Use the independently checked approval digest')
+    if not isinstance(external_id,str)or not re.fullmatch(r'[A-Za-z0-9_.:/-]{1,200}',external_id):raise ValueError('Use the independently verified accounting receipt identity')
+    if not isinstance(operator,str)or not re.fullmatch(r'[A-Za-z0-9_.@:/-]{1,200}',operator):raise ValueError('Record the accountable operator')
+    conn.execute('LOCK TABLE workflow.operations IN SHARE ROW EXCLUSIVE MODE');conn.execute('LOCK TABLE workflow.procrastinate_jobs IN SHARE ROW EXCLUSIVE MODE')
+    with conn.cursor(row_factory=tuple_row)as cur:
+        row=cur.execute('SELECT state,approved_hash,kind,source_ref,destination_contract,result,result_revision,lease_until FROM workflow.operations WHERE account_id=%s AND id=%s AND workflow_key=%s FOR UPDATE',(account_id,operation_id,extract)).fetchone()
+        active=cur.execute("SELECT EXISTS(SELECT 1 FROM workflow.procrastinate_jobs WHERE task_name=%s AND args->>'operation_id'=%s AND status='doing')",(dispatch,operation_id)).fetchone()[0]
+    if not row or row[0]not in {'unknown','dead'}or row[1]!=payload_sha256 or active or row[7]is not None:raise ValueError('Reconcile only an inactive uncertain delivery with its exact approval digest')
+    snapshot={'kind':row[2],'source':row[3],'destination':row[4],'result':row[5],'revision':row[6]}
+    if hashlib.sha256(canonical(snapshot,140000)).hexdigest()!=payload_sha256:raise ValueError('Approved snapshot changed; do not invent completion')
+    receipt={'externalId':external_id,'operationId':operation_id,'payloadSha256':payload_sha256,'reconciledBy':operator}
+    conn.execute("UPDATE workflow.operations SET state='sent',receipt=%s,updated_at=clock_timestamp() WHERE id=%s",(Jsonb(receipt),operation_id))
+    conn.execute("INSERT INTO workflow.events(operation_id,account_id,event,actor,detail)VALUES(%s,%s,'sent',%s,%s)",(operation_id,account_id,'operator:'+operator,Jsonb({'payloadSha256':payload_sha256,'reconciled':True})))
+    conn.execute("DELETE FROM workflow.procrastinate_jobs WHERE task_name=%s AND args->>'operation_id'=%s",(dispatch,operation_id))
+    return{'state':'sent','receipt':receipt}
+
+def set_membership(conn,*,account_id,subject,roles,active=True,namespace='invoice'):
+    owned_scope(conn,account_id,namespace)
+    if not isinstance(subject,str)or not 1<=len(subject.encode())<=500 or any(ord(c)<32 for c in subject):raise ValueError('Use the verified native login subject, never a display-name guess')
+    if type(active)is not bool or not isinstance(roles,list)or not roles or len(set(roles))!=len(roles)or not set(roles)<={'user','reviewer','supervisor','owner'}:raise ValueError('Use an explicit reviewed role set')
+    conn.execute('INSERT INTO workflow.accounts(id)VALUES(%s)ON CONFLICT DO NOTHING',(account_id,))
+    conn.execute('INSERT INTO workflow.memberships(account_id,subject,roles,active)VALUES(%s,%s,%s,%s)ON CONFLICT(account_id,subject)DO UPDATE SET roles=excluded.roles,active=excluded.active',(account_id,subject,roles,active))
+    return{'active':active,'roles':roles}

package/src/runtime/invoice_operator.py

@@ -0,0 +1,79 @@
+"""Explicit operator CLI; never run with the API or worker SQL identity.
+
+Connection/credential files are private local inputs, not export payloads. This
+tool performs destination writes only after --execute; obtain authorization first.
+It never contacts a model or the accounting service, and never claims that a human
+supplied receipt has been independently verified by this tool.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import stat
+import sys
+sys.path.insert(0,str(Path(__file__).resolve().parent))
+import psycopg
+from invoice_operator_core import validate_deployment,initialize_runtime
+from invoice_operations import purge_expired,quarantine_restored_deliveries,reconcile_completed,set_membership
+from structured_output import _object
+
+def private_json(path):
+    file=Path(path)
+    metadata=file.stat()
+    if not stat.S_ISREG(metadata.st_mode)or metadata.st_uid!=os.geteuid()or metadata.st_mode&0o077 or metadata.st_size>20000:raise ValueError('Use an owned mode-0600 bounded JSON input file')
+    value=json.loads(file.read_text(),object_pairs_hook=_object)
+    if not isinstance(value,dict):raise ValueError('Use a JSON object')
+    return value
+
+def connection_settings(path):
+    value=private_json(path)
+    if set(value)!={'host','port','dbname','user','passwordFile','caFile'}:raise ValueError('Use the documented operator connection fields')
+    secret=Path(value['passwordFile']);metadata=secret.stat()
+    if not secret.is_absolute()or metadata.st_uid!=os.geteuid()or metadata.st_mode&0o077 or not stat.S_ISREG(metadata.st_mode)or not 1<=metadata.st_size<=20000:raise ValueError('Use a private separately supplied database password/token file')
+    password=secret.read_text()
+    ca=Path(value['caFile'])
+    if not ca.is_absolute()or not ca.is_file()or b'-----BEGIN CERTIFICATE-----'not in ca.read_bytes():raise ValueError('Use the reviewed native CA bundle')
+    if any(not isinstance(value[key],str)or not value[key]or '\0'in value[key]for key in ['host','dbname','user'])or type(value['port'])is not int or not 1<=value['port']<=65535:raise ValueError('Use the owned native database connection')
+    if not password or '\0'in password:raise ValueError('Invalid private operator credential')
+    return dict(host=value['host'],port=value['port'],dbname=value['dbname'],user=value['user'],password=password,sslmode='verify-full',sslrootcert=str(ca),ssl_min_protocol_version='TLSv1.2',connect_timeout=5,options='-c search_path=pg_catalog,workflow,pg_temp -c statement_timeout=30000 -c lock_timeout=3000')
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action',choices=['initialize','membership','purge-expired','quarantine-restore','reconcile-completed'])
+    parser.add_argument('--connection-file',required=True);parser.add_argument('--deployment-file',required=True);parser.add_argument('--input-file');parser.add_argument('--execute',action='store_true');parser.add_argument('--confirm-workloads-stopped',action='store_true')
+    args=parser.parse_args(argv)
+    deployment=private_json(args.deployment_file)
+    scope=validate_deployment(deployment)
+    payload=private_json(args.input_file)if args.input_file else{}
+    if not args.execute:
+        print(json.dumps({'action':args.action,'willWrite':False,'next':'Review the destination, private inputs and authorization, then pass --execute. No database connection was made.'}));return
+    settings=connection_settings(args.connection_file)
+    if args.action=='initialize':
+        def passwords(purpose,principal):
+            if purpose not in deployment['bindings']or principal!=deployment['bindings'][purpose]['principal']:raise ValueError('Use the exact owned native password binding')
+            field=payload.get(purpose+'PasswordFile')
+            if not isinstance(field,str):raise ValueError('Supply a private separate IBM role password file')
+            path=Path(field);metadata=path.stat()
+            if not path.is_absolute()or metadata.st_uid!=os.geteuid()or metadata.st_mode&0o077 or not stat.S_ISREG(metadata.st_mode)or not 24<=metadata.st_size<=500:raise ValueError('Use an owned private strong runtime password file')
+            return path.read_text()
+        def connect(database=None):return psycopg.connect(**{**settings,**({'dbname':database}if database else{})})
+        receipt=initialize_runtime(connect,deployment,passwords=passwords if deployment['provider']=='ibm'else None)
+    else:
+        if args.action in {'purge-expired','quarantine-restore','reconcile-completed'}and not args.confirm_workloads_stopped:raise ValueError('Pause workloads and explicitly confirm the maintenance boundary')
+        with psycopg.connect(**settings)as conn:
+            if args.action=='membership':
+                if set(payload)!={'subject','roles','active'}:raise ValueError('Supply exact membership fields')
+                receipt=set_membership(conn,**scope,**payload)
+            elif args.action=='purge-expired':receipt=purge_expired(conn,**scope)
+            elif args.action=='quarantine-restore':receipt=quarantine_restored_deliveries(conn,**scope,workloads_stopped=True)
+            else:
+                if set(payload)!={'operation_id','payload_sha256','external_id','operator'}:raise ValueError('Supply the independently verified accounting completion receipt fields')
+                receipt=reconcile_completed(conn,**scope,**payload)
+    print(json.dumps({'action':args.action,'committed':True,'receipt':receipt}))
+
+if __name__=='__main__':
+    try:main()
+    except Exception:
+        # Driver exceptions can include connection fields or SQL parameter data.
+        # Keep private input details out of terminals and automated logs.
+        print('Operator action failed. No success is claimed. Check the private inputs, destination permissions, current schema and workload state.',file=sys.stderr);sys.exit(1)

package/src/runtime/invoice_operator_core.py

@@ -0,0 +1,39 @@
+"""Shared operator initialization for CLI and fixed native jobs, never HTTP.
+
+Validate the whole deployment before opening a connection. Authentication and
+transport belong to the caller's reviewed native credential factory; this module
+neither reads credentials nor chooses endpoints from model/request input.
+"""
+import re
+from workflow_role_bootstrap import canonical_uuid,validate_runtime_bindings,bootstrap_runtime_roles
+from workflow_database import initialize_database,grant_runtime_roles
+from invoice_operations import owned_scope
+
+def validate_deployment(deployment):
+    if not isinstance(deployment,dict)or set(deployment)!={'provider','deploymentId','accountId','namespace','bindings','tenantId'}:raise ValueError('Use the exact documented deployment identity')
+    canonical_uuid(deployment['accountId'])
+    if not isinstance(deployment['namespace'],str)or not re.fullmatch(r'[a-zA-Z0-9-]{1,20}',deployment['namespace']):raise ValueError('Use the owned workflow namespace')
+    if deployment['provider']!='azure'and deployment['tenantId']is not None:raise ValueError('Only the Azure profile has a native tenant mapping')
+    validate_runtime_bindings(provider=deployment['provider'],deployment_id=deployment['deploymentId'],bindings=deployment['bindings'],tenant_id=deployment['tenantId'])
+    return {'account_id':deployment['accountId'],'namespace':deployment['namespace']}
+
+def initialize_runtime(connect,deployment,*,passwords=None):
+    scope=validate_deployment(deployment)
+    if deployment['provider']=='ibm'and not callable(passwords):raise ValueError('Use the separate owned secret-store password reader')
+    # Native identity mapping and application schema are separate committed
+    # phases. A retry admits only exact ownership markers, never rotates existing
+    # SQL passwords, and then completes the application phase idempotently.
+    with connect('postgres'if deployment['provider']=='azure'else None)as conn:
+        if conn.autocommit:raise ValueError('Use an explicit operator transaction')
+        if conn.info.user in {item['name']for item in deployment['bindings'].values()}:raise PermissionError('Use the separate operator identity')
+        bootstrap_runtime_roles(conn,provider=deployment['provider'],deployment_id=deployment['deploymentId'],bindings=deployment['bindings'],tenant_id=deployment['tenantId'],passwords=passwords)
+    with connect(None)as conn:
+        if conn.autocommit:raise ValueError('Use an explicit operator transaction')
+        # Database-local and shared across deployments: serialize the check and
+        # CREATE, rather than allowing competing fresh-schema initializations.
+        conn.execute("SELECT pg_advisory_xact_lock(hashtextextended('atmem-workflow-schema-bootstrap-v1',0))")
+        if conn.execute("SELECT to_regnamespace('workflow')").fetchone()[0]is None:initialize_database(conn)
+        owned_scope(conn,**scope)
+        grant_runtime_roles(conn,deployment['bindings']['api']['name'],deployment['bindings']['worker']['name'],native_provider=deployment['provider'])
+        conn.execute('INSERT INTO workflow.accounts(id)VALUES(%s)ON CONFLICT DO NOTHING',(scope['account_id'],))
+    return {'initialized':True,'schemaVersion':1,'nativeIdentity':'Requires destination-native authentication checks; local success alone is insufficient.'}

package/src/runtime/invoice_operator_job.py

@@ -0,0 +1,147 @@
+"""Fixed native operator job entrypoint. Not an HTTP server or model tool.
+
+The emitted task supplies owned nonsecret deployment metadata and a separate
+operator identity. Credentials are platform secret references, never Terraform
+values. Execution is explicit; preview makes no SDK, secret-file or SQL calls.
+"""
+import argparse
+import base64
+from contextlib import contextmanager
+import http.client
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import sys
+import tempfile
+import time
+sys.path.insert(0,str(Path(__file__).resolve().parent))
+import psycopg
+from invoice_operator_core import validate_deployment,initialize_runtime
+from invoice_maintenance import maintain,monitor
+from invoice_configuration import owned_deployment,native_database,mounted_secret
+from structured_output import _object
+from workflow_connection import DatabaseConnection
+
+def deployment_input(environment,provider):
+    encoded=environment.get('OPERATOR_DEPLOYMENT_BASE64')
+    if not isinstance(encoded,str)or not 1<=len(encoded)<=16000:raise ValueError('Use the emitted bounded operator deployment')
+    deployment=json.loads(base64.b64decode(encoded,validate=True),object_pairs_hook=_object)
+    validate_deployment(deployment)
+    if deployment['provider']!=provider:raise ValueError('Operator provider differs from the bundled deployment')
+    return deployment
+
+@contextmanager
+def private_environment(provider,environment):
+    env=dict(environment)
+    if any(key.startswith(('MODEL_','DESTINATION_','PARSER_','DOCUMENT_'))for key in env):raise ValueError('Operator must not receive application/model/action authority')
+    if provider not in {'aws','azure','gcp','ibm'}:raise ValueError('Use the owned operator provider')
+    if provider not in {'aws','ibm'}and any(key in env for key in ['DATABASE_PASSWORD','DATABASE_PASSWORD_FILE']):raise ValueError('Use native workload database identity')
+    if provider!='ibm'and any(key in env for key in ['API_DATABASE_PASSWORD','WORKER_DATABASE_PASSWORD','API_DATABASE_PASSWORD_FILE','WORKER_DATABASE_PASSWORD_FILE']):raise ValueError('Runtime passwords are IBM-only bindings')
+    directory=Path(tempfile.mkdtemp(prefix='atmem-private-operator-'));directory.chmod(0o700)
+    try:
+        for key,maximum in [('DATABASE_PASSWORD',500),('API_DATABASE_PASSWORD',500),('WORKER_DATABASE_PASSWORD',500),('DATABASE_CA_PEM',256000)]:
+            if key not in env:continue
+            pointer='DATABASE_CA_FILE'if key=='DATABASE_CA_PEM'else key+'_FILE';value=env[key]
+            if pointer in env or not isinstance(value,str)or not value or len(value.encode())>maximum or'\0'in value:raise ValueError('Invalid or conflicting native operator secret injection')
+            if key=='DATABASE_CA_PEM'and'-----BEGIN CERTIFICATE-----'not in value:raise ValueError('Use the native database CA certificate')
+            path=directory/key.lower();descriptor=os.open(path,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)
+            with os.fdopen(descriptor,'wb')as stream:stream.write(value.encode())
+            env[pointer]=str(path);env.pop(key)
+            if environment is os.environ:os.environ.pop(key,None)
+        yield env
+    finally:shutil.rmtree(directory,ignore_errors=True)
+
+def native_connect(provider,env,deployment):
+    def connect(database=None):
+        settings={**env,**({'DATABASE_NAME':database}if database else{})}
+        if provider=='aws':
+            host=settings['DATABASE_HOST'];region=settings['REGION']
+            if not re.fullmatch(r'[a-z]{2}-[a-z]+-[0-9]',region)or not host.endswith('.'+region+'.rds.amazonaws.com'):raise ValueError('Use the owned regional RDS endpoint')
+            factory=DatabaseConnection('aws',host,5432,settings['DATABASE_NAME'],settings['DATABASE_USER'],mounted_secret(settings['DATABASE_PASSWORD_FILE']),ca_file=settings['DATABASE_CA_FILE'],role='migration')
+        else:factory=native_database(provider,settings,'migration')
+        if factory.parameters['user']in {row['name']for row in deployment['bindings'].values()}:raise PermissionError('Do not run an operator job as API or worker')
+        for attempt in range(3):
+            try:return psycopg.connect(factory())
+            except psycopg.OperationalError as error:
+                # Only retry connection establishment before any transaction.
+                # Cold proxy certificate/network setup can be transient; SQL
+                # permission/authentication/schema failures are never repaired
+                # by bypassing TLS, changing identities or replaying statements.
+                state=error.sqlstate
+                if provider!='gcp'or attempt==2 or(state is not None and not(state.startswith('08')or state=='57P03')):raise
+                time.sleep(attempt+1)
+    return connect
+
+def runtime_passwords(environment,deployment):
+    def password(purpose,principal):
+        if purpose not in deployment['bindings']or deployment['bindings'][purpose]['principal']!=principal:raise ValueError('Use the exact owned native password binding')
+        path=Path(environment[purpose.upper()+'_DATABASE_PASSWORD_FILE']);metadata=path.stat()
+        import stat
+        if not path.is_absolute()or not stat.S_ISREG(metadata.st_mode)or metadata.st_uid!=os.geteuid()or metadata.st_mode&0o077 or not 24<=metadata.st_size<=500:raise ValueError('Use a private separately supplied native runtime password')
+        return path.read_text()
+    return password
+
+def run_action(action,connect,deployment,*,passwords=None):
+    validate_deployment(deployment)
+    if action=='initialize':return {'status':'ok',**initialize_runtime(connect,deployment,passwords=passwords)}
+    if action=='maintain':return maintain(connect,deployment)
+    if action=='monitor':return monitor(connect,deployment)
+    raise ValueError('Unsupported operator job action')
+
+@contextmanager
+def private_proxy_job(provider,environment):
+    mode=environment.get('OPERATOR_PROXY_SHUTDOWN')
+    if mode is None:
+        yield;return
+    if provider!='gcp'or mode!='cloudsql-private-proxy'or environment.get('DATABASE_TRANSPORT')!='cloudsql-private-proxy':raise ValueError('Use the emitted Google job proxy lifecycle')
+    try:
+        # Stable GA job containers can start concurrently. Wait for the pinned
+        # proxy's own startup endpoint rather than depending on beta ordering.
+        deadline=time.monotonic()+30
+        while time.monotonic()<deadline:
+            startup=http.client.HTTPConnection('127.0.0.1',9090,timeout=1)
+            try:
+                startup.request('GET','/startup');response=startup.getresponse()
+                if response.status==200 and len(response.read(2049))<=2048:break
+            except (OSError,http.client.HTTPException):pass
+            finally:startup.close()
+            time.sleep(0.2)
+        else:raise TimeoutError('Private SQL proxy did not finish startup')
+        yield
+    finally:
+        # Fixed same-instance loopback endpoint; no configurable URL, redirects,
+        # ambient HTTP proxy or outbound credentials. A failed shutdown must not
+        # produce an ok receipt while the sidecar keeps the job running.
+        connection=http.client.HTTPConnection('127.0.0.1',9091,timeout=2)
+        try:
+            connection.request('POST','/quitquitquit',body=b'')
+            response=connection.getresponse()
+            if response.status!=200 or len(response.read(2049))>2048:raise ValueError('Private SQL proxy did not confirm shutdown')
+        finally:connection.close()
+
+def main(argv=None):
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action',choices=['initialize','maintain','monitor']);parser.add_argument('--execute',action='store_true');args=parser.parse_args(argv)
+    provider=owned_deployment()['provider']
+    if not args.execute:
+        deployment_input(os.environ,provider)
+        print(json.dumps({'format':'invoice-operator-v1','action':args.action,'status':'preview','willWrite':False}));return 0
+    def deadline(*_):raise TimeoutError('Operator execution deadline')
+    with private_proxy_job(provider,os.environ):
+        deployment=deployment_input(os.environ,provider)
+        previous=signal.signal(signal.SIGALRM,deadline);signal.alarm(900)
+        try:
+            with private_environment(provider,os.environ)as env:
+                result=run_action(args.action,native_connect(provider,env,deployment),deployment,passwords=runtime_passwords(env,deployment)if provider=='ibm'else None)
+        finally:signal.alarm(0);signal.signal(signal.SIGALRM,previous)
+    print(json.dumps({'format':'invoice-operator-v1','action':args.action,**result}))
+    return 0 if result['status']=='ok'else 2
+
+if __name__=='__main__':
+    try:sys.exit(main())
+    except Exception:
+        # Driver/SDK exceptions can contain sensitive endpoints, SQL or values.
+        print(json.dumps({'format':'invoice-operator-v1','status':'failed','code':'operator_job_failed'}));sys.exit(1)

package/src/runtime/invoice_parser_cli.py

@@ -0,0 +1,17 @@
+"""Credentialless one-shot parser protocol; no URLs, cloud calls or model work."""
+import hashlib
+import json
+import sys
+from pathlib import Path
+sys.path.insert(0,str(Path(__file__).resolve().parent))
+from invoice_document import PdfDocument,DocumentError
+
+if __name__=='__main__':
+    try:
+        raw=sys.stdin.buffer.read(10000001)
+        document=PdfDocument().extract(raw,hashlib.sha256(raw).hexdigest())
+        sys.stdout.write(json.dumps({'status':'ok','document':document},ensure_ascii=False))
+    except DocumentError as error:
+        sys.stdout.write(json.dumps({'status':'rejected','reason':error.code}));sys.exit(2)
+    except Exception:
+        sys.stdout.write(json.dumps({'status':'rejected','reason':'extraction_unavailable'}));sys.exit(2)

package/src/runtime/invoice_parser_identity.py

@@ -0,0 +1,39 @@
+"""Parser-only Entra workload authorization; no application/cloud credentials.
+
+The issuer/key endpoint, audience and exact worker identities are compiler-owned.
+Staff/delegated tokens and another application in the same tenant grant no access.
+This module does not claim that a valid token proves a native deployment exists.
+"""
+import re
+import hmac
+import jwt
+
+UUID=r'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
+
+class EntraParserVerifier:
+    def __init__(self,tenant,audience,worker_client,worker_principal,*,jwks=None):
+        if any(not isinstance(value,str)or not re.fullmatch(UUID,value)for value in [tenant,audience,worker_client,worker_principal]):raise ValueError('Use exact owned Entra parser and worker identities')
+        self.tenant=tenant;self.audience=audience;self.worker_client=worker_client;self.worker_principal=worker_principal
+        self.issuer='https://login.microsoftonline.com/'+tenant+'/v2.0'
+        self.jwks=jwks or jwt.PyJWKClient('https://login.microsoftonline.com/'+tenant+'/discovery/v2.0/keys',timeout=2,lifespan=300)
+    def __call__(self,token):
+        try:
+            if not isinstance(token,str)or not 1<=len(token)<=16384:raise ValueError('Invalid workload token')
+            header=jwt.get_unverified_header(token)
+            if header.get('alg')!='RS256'or not isinstance(header.get('kid'),str)or not 1<=len(header['kid'])<=200:raise ValueError('Invalid workload signing key')
+            key=self.jwks.get_signing_key_from_jwt(token).key
+            claims=jwt.decode(token,key,algorithms=['RS256'],issuer=self.issuer,audience=self.audience,leeway=30,options={'require':['iss','aud','iat','nbf','exp','tid','oid','azp','ver','roles']})
+            if(claims['aud']!=self.audience or claims['tid']!=self.tenant or claims['oid']!=self.worker_principal or claims['azp']!=self.worker_client or claims['ver']!='2.0'
+               or'scp'in claims or claims.get('idtyp','app')!='app'or not isinstance(claims['roles'],list)or not 1<=len(claims['roles'])<=100 or any(not isinstance(role,str)for role in claims['roles'])or'Parser.Invoke'not in claims['roles']
+               or any(type(claims[name])is not int for name in ['iat','nbf','exp'])or not 0<claims['exp']-claims['iat']<=86700):raise ValueError('Caller is not the owned parser worker')
+            return self.worker_principal
+        except Exception:raise PermissionError('Authorized parser worker required')from None
+
+class SharedParserVerifier:
+    """Private TLS RPC admission only; this token confers no cloud/data authority."""
+    def __init__(self,token):
+        if not isinstance(token,str)or not re.fullmatch(r'[0-9a-f]{64}',token):raise ValueError('Use a separately provisioned 256-bit parser token')
+        self._token=token
+    def __call__(self,token):
+        if not isinstance(token,str)or not re.fullmatch(r'[0-9a-f]{64}',token)or not hmac.compare_digest(self._token,token):raise PermissionError('Authorized parser worker required')
+        return'owned-worker'