@atmem/architect 0.0.0-stage → 0.2.0-alpha.4.1

package/src/runtime/workflow_review.py

@@ -0,0 +1,106 @@
+"""Explicit review/access/semantic policy supplied by trusted application code.
+
+No domain fields, provider selection, executable loading or user configuration.
+Semantic validators may reject data, never normalize it. Their implementation and
+declared source dependencies are approval-bound; this is not a Python sandbox or
+proof that a trusted validator is pure, bounded, or declares every dependency.
+"""
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import re
+import types
+if __package__:
+    from .workflow_payload import PayloadContract, encoded
+else:
+    from workflow_payload import PayloadContract, encoded
+
+
+@dataclass(frozen=True, init=False)
+class ReviewPolicy:
+    _encoded: bytes
+    _sources: tuple
+    _validator: object
+    _payload: PayloadContract
+
+    def __init__(self, payload, *, id, editable_fields, read_scope='owner',
+                 inspection_ttl_seconds=300, validator=None, validation_sources=()):
+        if type(payload) is not PayloadContract:
+            raise ValueError('Supply the exact owned payload contract')
+        if type(id) is not str or not re.fullmatch(r'[a-z][a-z0-9-]{0,79}', id):
+            raise ValueError('Use a versioned owned review policy identity')
+        fields = payload.fields('result')
+        if (type(editable_fields) not in {list, tuple} or
+            any(type(field) is not str for field in editable_fields) or
+            len(set(editable_fields)) != len(editable_fields) or not set(editable_fields) <= set(fields)):
+            raise ValueError('Declare the editable top-level result fields explicitly')
+        if type(read_scope) is not str or read_scope not in {'owner', 'account'}:
+            raise ValueError('Use an explicit application read scope')
+        if inspection_ttl_seconds is not None and (type(inspection_ttl_seconds) is not int or not 1 <= inspection_ttl_seconds <= 3600):
+            raise ValueError('Use a bounded inspection lifetime or explicit None')
+        if type(validation_sources) not in {list, tuple, dict} or len(validation_sources) > 32:
+            raise ValueError('Declare bounded trusted validator source dependencies')
+        if validator is not None and (type(validator) is not types.FunctionType or validator.__closure__):
+            raise ValueError('Supply a trusted module-level semantic validator, not executable data')
+        if (validator is None) != (not validation_sources):
+            raise ValueError('A semantic validator requires its explicit source dependencies')
+        sources = []
+        entries = validation_sources.items() if type(validation_sources) is dict else [(Path(source).name,source) for source in validation_sources]
+        labels = set()
+        for label, source in entries:
+            if (type(label) is not str or len(label)>512 or '\\' in label or
+                PurePosixPath(label).is_absolute() or any(not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_.-]{0,127}',part) or part in {'.','..'} for part in label.split('/'))):
+                raise ValueError('Use explicit portable relative validator dependency labels')
+            if label in labels:raise ValueError('Use explicit relative source labels for duplicate filenames')
+            labels.add(label)
+            path = Path(source)
+            if path.is_symlink() or not path.is_file() or path.stat().st_size > 1048576:
+                raise ValueError('Use bounded regular validator source files')
+            path = path.resolve()
+            sources.append((label, path, hashlib.sha256(path.read_bytes()).hexdigest()))
+        if validator is not None and Path(validator.__code__.co_filename).resolve() not in {path for _, path, _ in sources}:
+            raise ValueError('The semantic validator implementation must be source-bound')
+        mechanism = Path(__file__).resolve()
+        mechanism_sha256 = hashlib.sha256(mechanism.read_bytes()).hexdigest()
+        definition = {'version': 1, 'id': id, 'payloadContractSha256': payload.sha256,
+                      'mechanismSha256': mechanism_sha256,
+                      'editableFields': sorted(editable_fields), 'readScope': read_scope,
+                      'inspectionTtlSeconds': inspection_ttl_seconds,
+                      'validator': None if validator is None else {
+                          'entrypoint': validator.__qualname__,
+                          'sources': {label: sha for label, _, sha in sorted(sources)}}}
+        object.__setattr__(self, '_encoded', encoded(definition))
+        object.__setattr__(self, '_sources', tuple((path,sha) for _,path,sha in sources)+((mechanism, mechanism_sha256),))
+        object.__setattr__(self, '_validator', validator)
+        object.__setattr__(self, '_payload', payload)
+
+    @property
+    def data(self): return json.loads(self._encoded)
+
+    @property
+    def sha256(self): return hashlib.sha256(self._encoded).hexdigest()
+
+    def ensure_current(self):
+        for path, sha in self._sources:
+            if path.is_symlink() or not path.is_file() or path.stat().st_size > 1048576 or hashlib.sha256(path.read_bytes()).hexdigest() != sha:
+                raise ValueError('Review validator sources changed; qualify a new policy binding')
+
+    def validate_result(self, source, result):
+        self.ensure_current()
+        original = self._payload.validate('source', source)
+        value = self._payload.validate('result', result)
+        if self._validator is not None:
+            before = (encoded(original), encoded(value))
+            returned = self._validator(original, value)
+            if returned is not None or (encoded(original), encoded(value)) != before:
+                raise ValueError('Semantic validation must only accept or reject, never transform data')
+        return value
+
+    def validate_edit(self, source, previous, result):
+        value = self.validate_result(source, result)
+        previous = self._payload.validate('result', previous)
+        editable = set(self.data['editableFields'])
+        if encoded({k: v for k, v in previous.items() if k not in editable}) != encoded({k: v for k, v in value.items() if k not in editable}):
+            raise ValueError('Only explicitly editable result fields may change')
+        return value

package/src/runtime/workflow_role_bootstrap.py

@@ -0,0 +1,104 @@
+"""Operator-only native SQL identity bootstrap; never an application endpoint.
+
+Create owned logins, preserve unrelated existing roles, and never implicitly rotate
+an existing password. Google IAM users must first be created by this package's
+native Cloud SQL user resource. Azure mappings use authoritative object/tenant IDs,
+not display-name guesses. Execute only during an authorized destination bootstrap.
+"""
+import json
+import re
+import uuid
+from psycopg import sql
+from psycopg.rows import tuple_row
+
+def canonical_uuid(value):
+    if not isinstance(value,str)or str(uuid.UUID(value))!=value:raise ValueError('Use a canonical owned UUID')
+    return value
+
+def role_marker(provider,deployment_id,purpose,binding):
+    return'atmem-owned-runtime-v1:'+json.dumps({'provider':provider,'deployment':deployment_id,'purpose':purpose,'principal':binding['principal']},sort_keys=True,separators=(',',':'))
+
+def azure_principal(conn,name):
+    # Named output aliases avoid relying on case folding of Microsoft's documented
+    # camel-case output labels, while preserving its exact six-column contract.
+    with conn.cursor(row_factory=tuple_row)as cursor:
+        return cursor.execute('SELECT role_name::text,principal_type,object_id,tenant_id,mfa,admin FROM pg_catalog.pgaadauth_list_principals(false) AS mapped(role_name,principal_type,object_id,tenant_id,mfa,admin) WHERE role_name=%s',(name,)).fetchone()
+
+def validate_runtime_bindings(*,provider,deployment_id,bindings,tenant_id=None):
+    canonical_uuid(deployment_id)
+    if provider not in {'aws','azure','gcp','ibm'}or not isinstance(bindings,dict)or set(bindings)!={'api','worker'}:raise ValueError('Use the complete owned native role bindings')
+    if provider=='azure':
+        canonical_uuid(tenant_id)
+    names=[]
+    for purpose,binding in bindings.items():
+        fields={'name','principal','created_by_package'}if provider=='gcp'else{'name','principal'}
+        if not isinstance(binding,dict)or set(binding)!=fields or not isinstance(binding['name'],str)or not re.fullmatch(r'[A-Za-z0-9_.@-]{1,63}',binding['name']):raise ValueError('Invalid native SQL role binding')
+        principal=binding['principal']
+        if provider in {'azure','ibm'}:canonical_uuid(principal)
+        elif provider=='aws':
+            if not isinstance(principal,str)or not re.fullmatch(r'arn:aws:iam::[0-9]{12}:role/[A-Za-z0-9+=,.@_/-]{1,512}',principal):raise ValueError('Use the exact owned workload role ARN')
+        else:
+            if(binding['created_by_package']is not True or not isinstance(principal,str)or not re.fullmatch(r'[a-z][a-z0-9-]{4,29}@[a-z][a-z0-9-]{4,28}[a-z0-9]\.iam\.gserviceaccount\.com',principal)or binding['name']!=principal.removesuffix('.gserviceaccount.com')):raise ValueError('Only the package-created service account IAM user may be admitted here')
+        names.append(binding['name'])
+    if len(set(names))!=2:raise ValueError('API and worker logins must be separate')
+    return bindings
+
+def bootstrap_runtime_roles(conn,*,provider,deployment_id,bindings,passwords=None,tenant_id=None):
+    validate_runtime_bindings(provider=provider,deployment_id=deployment_id,bindings=bindings,tenant_id=tenant_id)
+    if provider=='azure'and conn.info.dbname!='postgres':raise ValueError('Azure principal mapping must run on the native postgres database before application schema bootstrap')
+    if provider=='ibm'and not callable(passwords):raise ValueError('Use the separate owned secret-store password reader')
+    # Serialize bootstrap for one deployment, including retries after a partial
+    # operator run. This lock does not confer ownership over an unrelated role.
+    conn.execute('SELECT pg_advisory_xact_lock(hashtextextended(%s,0))',('atmem-native-role-bootstrap:'+deployment_id,))
+    result={}
+    for purpose,binding in bindings.items():
+        name=binding['name'];identifier=sql.Identifier(name);marker=role_marker(provider,deployment_id,purpose,binding)
+        with conn.cursor(row_factory=tuple_row)as cursor:
+            existing=cursor.execute("SELECT r.oid,shobj_description(r.oid,'pg_authid'),r.rolsuper,r.rolcreatedb,r.rolcreaterole,r.rolreplication,r.rolbypassrls,r.rolcanlogin FROM pg_roles r WHERE rolname=%s",(name,)).fetchone()
+        if existing:
+            if any(existing[2:7])or not existing[7]:raise ValueError('Native runtime role must be a nonadministrative login')
+            if existing[1]!=marker:
+                if provider!='gcp'or existing[1]is not None:raise ValueError('Refusing to adopt or repoint an unrelated existing database role')
+                with conn.cursor(row_factory=tuple_row)as cursor:
+                    parents=cursor.execute('SELECT p.rolname FROM pg_auth_members m JOIN pg_roles p ON p.oid=m.roleid WHERE m.member=%s',(existing[0],)).fetchall()
+                if not parents or not {row[0]for row in parents}<={'cloudsqliamuser','cloudsqliamserviceaccount'}:raise ValueError('The native service-account authentication marker is missing or broadened')
+                # Complete ownership/effective-grant admission still runs in the
+                # application database before runtime grants are installed.
+                conn.execute(sql.SQL('COMMENT ON ROLE {} IS {}').format(identifier,sql.Literal(marker)))
+        elif provider=='gcp':raise ValueError('Apply the owned Cloud SQL IAM user resource before SQL bootstrap')
+        elif provider=='azure':
+            conn.execute("SELECT pg_catalog.pgaadauth_create_principal_with_oid(%s,%s,'service',false,false)",(name,binding['principal']))
+            conn.execute(sql.SQL('COMMENT ON ROLE {} IS {}').format(identifier,sql.Literal(marker)))
+        else:
+            password=sql.SQL('NULL')
+            if provider=='ibm':
+                secret=passwords(purpose,binding['principal'])
+                if not isinstance(secret,str)or not 24<=len(secret.encode('utf-8'))<=500 or '\0'in secret:raise ValueError('Use a strong operator-managed SQL credential')
+                # Send a client-side SCRAM verifier rather than plaintext in SQL
+                # DDL/statement logs. The verifier remains sensitive DBA metadata.
+                verifier=conn.pgconn.encrypt_password(secret.encode(),name.encode(),algorithm=b'scram-sha-256').decode('ascii');password=sql.Literal(verifier)
+            conn.execute(sql.SQL('CREATE ROLE {} LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS PASSWORD {}').format(identifier,password))
+            if provider=='aws':
+                with conn.cursor(row_factory=tuple_row)as cursor:available=cursor.execute("SELECT 1 FROM pg_roles WHERE rolname='rds_iam'").fetchone()
+                if not available:raise ValueError('The native RDS IAM authentication role is missing')
+                conn.execute(sql.SQL('GRANT rds_iam TO {}').format(identifier))
+            conn.execute(sql.SQL('COMMENT ON ROLE {} IS {}').format(identifier,sql.Literal(marker)))
+        if provider=='azure':
+            mapped=azure_principal(conn,name)
+            if not mapped or len(mapped)!=6 or mapped[0]!=name or mapped[1]!='service'or mapped[2]!=binding['principal']or mapped[3]!=tenant_id or mapped[4]!=0 or mapped[5]!=0:raise ValueError('Native Entra role mapping differs from the owned service principal/tenant or has administrator/MFA flags')
+        # Re-read after native creation as well as on repeat operator runs. A
+        # provider function must not silently install an administrative login.
+        with conn.cursor(row_factory=tuple_row)as cursor:
+            flags=cursor.execute('SELECT rolsuper,rolcreatedb,rolcreaterole,rolreplication,rolbypassrls,rolcanlogin FROM pg_roles WHERE rolname=%s',(name,)).fetchone()
+            parents=cursor.execute('SELECT p.rolname FROM pg_auth_members m JOIN pg_roles p ON p.oid=m.roleid JOIN pg_roles child ON child.oid=m.member WHERE child.rolname=%s',(name,)).fetchall()
+        if not flags or any(flags[:5])or not flags[5]:raise ValueError('Native runtime role must be a nonadministrative login')
+        allowed={'rds_iam'}if provider=='aws'else{'cloudsqliamuser','cloudsqliamserviceaccount'}if provider=='gcp'else set()
+        if not {row[0]for row in parents}<=allowed:raise ValueError('Native runtime role has an unreviewed inherited authority')
+        if provider=='aws':
+            # Repair only the authentication membership of an already owned
+            # role. Never adopt unrelated logins or remove another grant.
+            conn.execute(sql.SQL('GRANT rds_iam TO {}').format(identifier))
+        if provider=='gcp'and not parents:raise ValueError('Native Cloud SQL IAM authentication membership is missing')
+        conn.execute(sql.SQL('ALTER ROLE {} CONNECTION LIMIT {}').format(identifier,sql.Literal(48 if purpose=='api'else 24)))
+        result[purpose]=name
+    return result

package/src/runtime/workflow_schema.sql

@@ -0,0 +1,72 @@
+-- Apply only through the reviewed migration role, in its own database/schema.
+-- Queue schema is supplied by the pinned Procrastinate dependency, not copied here.
+CREATE TABLE workflow.schema_version (
+    version integer PRIMARY KEY CHECK (version = 2),
+    source_sha256 text NOT NULL,
+    queue_version text NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+CREATE TABLE workflow.accounts (
+    id uuid PRIMARY KEY
+);
+CREATE TABLE workflow.memberships (
+    account_id uuid NOT NULL REFERENCES workflow.accounts(id),
+    subject text NOT NULL CHECK (octet_length(subject) BETWEEN 1 AND 500),
+    roles text[] NOT NULL CHECK (cardinality(roles) > 0 AND roles <@ ARRAY['user','reviewer','supervisor','owner']::text[]),
+    active boolean NOT NULL DEFAULT true,
+    authorization_lock bigint NOT NULL DEFAULT 0,
+    PRIMARY KEY (account_id, subject)
+);
+CREATE TABLE workflow.operations (
+    id uuid PRIMARY KEY,
+    account_id uuid NOT NULL REFERENCES workflow.accounts(id),
+    workflow_key text NOT NULL CHECK (octet_length(workflow_key) BETWEEN 1 AND 128),
+    kind text NOT NULL CHECK (kind IN ('document','draft','account_change')),
+    dedup_key text NOT NULL CHECK (octet_length(dedup_key) BETWEEN 1 AND 200),
+    created_by text NOT NULL,
+    -- Payload JSON must retain every accepted Unicode scalar, including U+0000.
+    -- Do not cast these fields to jsonb/text scalars: PostgreSQL cannot represent
+    -- NUL in text. Application contracts validate and canonically bind the JSON.
+    source_ref json NOT NULL CHECK (json_typeof(source_ref) = 'object'),
+    destination_contract jsonb NOT NULL CHECK (jsonb_typeof(destination_contract) = 'object'),
+    state text NOT NULL CHECK (state IN ('pending','processing','review','approved','dispatching','unknown','sent','dead')),
+    result json,
+    result_revision integer NOT NULL DEFAULT 0,
+    approved_hash text,
+    approved_by text,
+    lease_token uuid,
+    lease_until timestamptz,
+    execution_epoch bigint NOT NULL DEFAULT 0,
+    attempts integer NOT NULL DEFAULT 0,
+    queue_job_id bigint,
+    receipt json,
+    created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+    updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+    UNIQUE (account_id, workflow_key, kind, dedup_key),
+    UNIQUE (id, account_id),
+    FOREIGN KEY (account_id, created_by) REFERENCES workflow.memberships(account_id, subject),
+    FOREIGN KEY (account_id, approved_by) REFERENCES workflow.memberships(account_id, subject),
+    CHECK ((lease_token IS NULL) = (lease_until IS NULL))
+);
+CREATE INDEX workflow_operations_recovery ON workflow.operations(state, lease_until);
+CREATE TABLE workflow.results_history (
+    operation_id uuid NOT NULL,
+    account_id uuid NOT NULL,
+    revision integer NOT NULL CHECK (revision > 0),
+    result json NOT NULL CHECK (json_typeof(result) = 'object' AND octet_length(result::text) <= 70000),
+    actor text NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+    PRIMARY KEY (operation_id,revision),
+    FOREIGN KEY (operation_id,account_id) REFERENCES workflow.operations(id,account_id)
+);
+CREATE TABLE workflow.events (
+    sequence bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    operation_id uuid NOT NULL,
+    account_id uuid NOT NULL,
+    event text NOT NULL,
+    actor text NOT NULL,
+    detail jsonb NOT NULL CHECK (jsonb_typeof(detail) = 'object' AND octet_length(detail::text) <= 2000),
+    created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+    FOREIGN KEY (operation_id, account_id) REFERENCES workflow.operations(id, account_id)
+);
+CREATE INDEX workflow_events_operation ON workflow.events(account_id, operation_id, sequence);

package/src/runtime/workflow_worker.py

@@ -0,0 +1,142 @@
+"""Owned queue integration; concrete processors/HTTP adapters remain separate.
+
+Task arguments contain an operation UUID only. Callbacks are trusted source wired
+by the compiler/bootstrap, never model-provided paths, tools or Python code.
+"""
+import asyncio
+import logging
+import time
+import procrastinate
+import psycopg
+from durable_workflow import WorkflowStore,LostLease
+from workflow_connection import DatabaseCredentialUnavailable
+from workflow_errors import TemporaryWork,PermanentWork,ExternalOutcomeUnknown,DestinationNotAttempted,InvalidDispatch
+from workflow_contract import bind_review_policy
+
+def _transient_database_error(error,depth=0):
+    # ConnectorException and TaskGroup wrappers retain the native cause. Never
+    # retry a mixed group containing a programming/schema/authorization failure.
+    if depth>12:return False
+    if isinstance(error,BaseExceptionGroup):return bool(error.exceptions)and all(_transient_database_error(child,depth+1)for child in error.exceptions)
+    if isinstance(error,DatabaseCredentialUnavailable):return True
+    if isinstance(error,psycopg.OperationalError):
+        state=error.sqlstate
+        return state is None or state.startswith('08')or state in {'57P01','57P02','57P03'}
+    if error.__cause__ is not None:return _transient_database_error(error.__cause__,depth+1)
+    return False
+
+def _namespace(value):
+    if not isinstance(value,str)or not value.isascii()or not value.replace('-','').isalnum()or not 1<=len(value)<=20:raise ValueError('Invalid owned workflow namespace')
+    return value
+
+def producer_store(dsn,*,destination_contract,namespace='workflow',lease_seconds=600,payload_contract=None,operation_kind=None,review_policy=None):
+    """API-side store: synchronous outbox, no worker/model credentials needed."""
+    namespace=_namespace(namespace)
+    app=procrastinate.App(connector=procrastinate.SyncPsycopgConnector(conninfo=dsn,kwargs={'connect_timeout':5,'options':'-c search_path=pg_catalog,workflow,pg_temp'}))
+    def worker_only(operation_id):raise PermanentWork('Run the dedicated owned worker, not an API-side producer')
+    extract=app.task(name=namespace+'.extract',queue=namespace+'-extract')(worker_only)
+    dispatch=app.task(name=namespace+'.dispatch',queue=namespace+'-dispatch')(worker_only)
+    return WorkflowStore(dsn,extract,dispatch,destination_contract=destination_contract,lease_seconds=lease_seconds,payload_contract=payload_contract,operation_kind=operation_kind,review_policy=review_policy)
+
+class WorkflowRuntime:
+    def __init__(self,dsn,processor,deliver,*,destination_contract=None,idempotent_destination=False,namespace='workflow',lease_seconds=600,retry_wait=5,payload_contract=None,operation_kind=None,review_policy=None):
+        if type(idempotent_destination)is not bool:raise ValueError('Invalid owned worker configuration')
+        namespace=_namespace(namespace)
+        if type(retry_wait)is not int or not 0<=retry_wait<=300:raise ValueError('Invalid retry policy')
+        for stage in [processor,deliver]:
+            if hasattr(stage,'timeout_seconds')and stage.timeout_seconds+5>=lease_seconds:raise ValueError('A stage deadline must leave room to commit inside the domain lease')
+        if hasattr(deliver,'idempotency_verified')and deliver.idempotency_verified!=idempotent_destination:raise ValueError('Worker replay policy must match the reviewed destination contract')
+        if destination_contract is None:destination_contract=getattr(deliver,'contract',None)
+        elif hasattr(deliver,'contract')and deliver.contract!=bind_review_policy(destination_contract,payload_contract,review_policy):raise ValueError('Worker and destination integration identities must match')
+        if review_policy is not None and hasattr(deliver,'contract')and deliver.contract!=bind_review_policy(destination_contract,payload_contract,review_policy):raise ValueError('Publisher must use the exact review policy binding')
+        self.processor=processor;self.deliver=deliver;self.idempotent_destination=idempotent_destination
+        async def refreshed_connection():return await asyncio.to_thread(dsn)
+        self.app=procrastinate.App(connector=procrastinate.PsycopgConnector(conninfo=refreshed_connection if callable(dsn)else dsn,min_size=1,max_size=8,max_lifetime=600,kwargs={'connect_timeout':5,'options':'-c search_path=pg_catalog,workflow,pg_temp -c statement_timeout=10000 -c lock_timeout=3000'}))
+        retry=procrastinate.RetryStrategy(max_attempts=5,wait=retry_wait,retry_exceptions=[TemporaryWork])
+        self.extract=self.app.task(name=namespace+'.extract',queue=namespace+'-extract',retry=retry)(self._extract)
+        self.dispatch=self.app.task(name=namespace+'.dispatch',queue=namespace+'-dispatch',retry=retry)(self._dispatch)
+        # The domain transaction is a synchronous psycopg connection. Keep its
+        # producer connector synchronous even while the async worker pool is open;
+        # never accidentally bridge that connection into an async cursor context.
+        self.store=producer_store(dsn,destination_contract=destination_contract,namespace=namespace,lease_seconds=lease_seconds,payload_contract=payload_contract,operation_kind=operation_kind,review_policy=review_policy)
+    async def _fail(self,row,reason,*,retryable=False,ambiguous=True):
+        try:await asyncio.to_thread(self.store.fail,str(row['id']),str(row['lease_token']),reason,retryable=retryable,ambiguous=ambiguous)
+        except LostLease:return
+    async def _extract(self,operation_id):
+        try:row=await asyncio.to_thread(self.store.claim_extract,operation_id)
+        except psycopg.OperationalError:raise TemporaryWork('Database connection temporarily unavailable before processing')from None
+        if row is None:return
+        try:
+            result=await asyncio.to_thread(self.processor,row)
+            await asyncio.to_thread(self.store.record_result,operation_id,str(row['lease_token']),result)
+        except LostLease:return
+        except TemporaryWork:
+            await self._fail(row,'model_unavailable',retryable=True);raise TemporaryWork('Processing temporarily unavailable')from None
+        except BaseException as error:
+            if isinstance(error,asyncio.CancelledError):raise
+            await self._fail(row,'invalid_result');raise PermanentWork('Processing requires review or recovery')from None
+    async def _dispatch(self,operation_id):
+        try:row=await asyncio.to_thread(self.store.claim_dispatch,operation_id,verified_idempotent_replay=self.idempotent_destination)
+        except psycopg.OperationalError:raise TemporaryWork('Database connection temporarily unavailable before dispatch')from None
+        if row is None:return
+        try:
+            receipt=await asyncio.to_thread(self.deliver,row,idempotency_key=str(row['id']),payload_sha256=row['approved_hash'])
+            await asyncio.to_thread(self.store.record_sent,operation_id,str(row['lease_token']),receipt)
+        except LostLease:return
+        except DestinationNotAttempted:
+            await self._fail(row,'destination_unavailable',retryable=True,ambiguous=False);raise TemporaryWork('Destination credential temporarily unavailable; no request was made')from None
+        except InvalidDispatch:
+            await self._fail(row,'destination_rejected',ambiguous=False);raise PermanentWork('Approved dispatch integrity requires review; no request was made')from None
+        except ExternalOutcomeUnknown:
+            await self._fail(row,'destination_unavailable',retryable=True,ambiguous=True)
+            if self.idempotent_destination:raise TemporaryWork('Destination acknowledgement unavailable; stable replay contract applies')from None
+            raise PermanentWork('External outcome requires reconciliation before another attempt')from None
+        except BaseException as error:
+            if isinstance(error,asyncio.CancelledError):raise
+            # An unexpected exception can happen after the external service
+            # accepted the request, including while committing its receipt.
+            await self._fail(row,'destination_unavailable',ambiguous=True)
+            raise PermanentWork('External outcome requires reconciliation')from None
+    async def recover_once(self):
+        # Native heartbeat-based stale detection, never duration-only retry of an
+        # actively heartbeating worker. Domain fencing protects resumed callbacks.
+        for owned_task in [self.extract,self.dispatch]:
+            stalled=await self.app.job_manager.get_stalled_jobs(task_name=owned_task.name,seconds_since_heartbeat=60)
+            for job in stalled:await self.app.job_manager.retry_job(job)
+        expired=await asyncio.to_thread(self.store.recover_expired)
+        repaired=await asyncio.to_thread(self.store.reconcile_notifications)
+        return list(dict.fromkeys([*expired,*repaired]))
+    async def run(self,*,concurrency=2,recovery_interval=30,**options):
+        if type(concurrency)is not int or not 1<=concurrency<=10 or type(recovery_interval)is not int or not 5<=recovery_interval<=300:raise ValueError('Invalid bounded worker options')
+        delay=1
+        while True:
+            started=time.monotonic()
+            try:
+                # Close even when the initial pool wait fails: retaining a
+                # partially opened pool would bypass fresh credentials on retry.
+                try:
+                    # Admit the exact owned schema before queue registration,
+                    # heartbeat/recovery writes or fetching a notification.
+                    def admit():
+                        with self.store.connect():pass
+                    await asyncio.to_thread(admit)
+                    await self.app.open_async()
+                    async def recovery():
+                        while True:
+                            await self.recover_once();await asyncio.sleep(recovery_interval)
+                    worker_options={'update_heartbeat_interval':10.0,'stalled_worker_timeout':90.0,**options}
+                    async with asyncio.TaskGroup()as group:
+                        task=group.create_task(recovery())
+                        worker=group.create_task(self.app.run_worker_async(queues=[self.extract.queue,self.dispatch.queue],concurrency=concurrency,**worker_options))
+                        try:await worker
+                        finally:task.cancel()
+                finally:await self.app.close_async()
+                return
+            except Exception as error:
+                if not _transient_database_error(error):raise
+                # Domain leases, approval hashes and uncertain-delivery rules
+                # remain authoritative. Reopening a queue pool cannot resend an
+                # external action or reset an operation's attempts/lease.
+                logging.getLogger(__name__).warning('Queue database connection interrupted; reconnecting with fresh workload credentials')
+                if time.monotonic()-started>=30:delay=1
+                await asyncio.sleep(delay);delay=min(delay*2,30)

package/src/runtime-settings.mjs

@@ -0,0 +1,15 @@
+import {structuredContract} from './structured-contract.mjs';
+const ranges={containerMemoryBytes:[1,Number.MAX_SAFE_INTEGER],memoryMb:[128,10240],functionTimeoutSeconds:[1,900],concurrency:[1,1000],maxInputBytes:[1,1000000],maxOutputTokens:[1,4096],maxPdfBytes:[1,20000000],maxPdfPages:[1,1000],retentionDays:[1,3653]};
+export const LOG_RETENTION_DAYS=[1,3,5,7,14,30,60,90,120,150,180,365,400,545,731,1096,1827,2192,2557,2922,3288,3653];
+export function runtimeSettings(config={}){
+ const result={};
+ if(config?.outputContract!=null)result.outputContract=structuredContract(config.outputContract);
+ for(const [name,[min,max]]of Object.entries(ranges)){
+  const value=config?.[name];if(value==null)continue;
+  if(!Number.isInteger(value)||value<min||value>max)throw Error(`Invalid ${name}: use an integer from ${min} to ${max}.`);
+  result[name]=value;
+ }
+ if(config?.logRetentionDays!=null){if(!LOG_RETENTION_DAYS.includes(config.logRetentionDays))throw Error('Choose a supported finite CloudWatch retention period.');result.logRetentionDays=config.logRetentionDays;}
+ if(config?.modelId!=null){if(typeof config.modelId!=="string"||config.modelId.length>150||!/^[a-z0-9][a-z0-9.-]*:[0-9]+$/.test(config.modelId))throw Error('Use a direct foundation-model ID including version.');result.modelId=config.modelId;}
+ return result;
+}

package/src/s3-access.mjs

@@ -0,0 +1,14 @@
+// Explicit capabilities only: diagram labels never grant access.
+export const S3_ACCESS_MODES = ['s3-read', 's3-read-write'];
+export const IAM_PRINCIPAL_BINDING = 'aws-iam-principal';
+export function storageAccessPlan(project, rows) {
+ const nodes=new Map(project.nodes.map(n=>[n.id,n]));
+ const resources=new Map(rows.map(r=>[r.id,r]));
+ const connections=project.edges.flatMap(edge=>{
+  const source=nodes.get(edge.source),target=resources.get(edge.target);
+  if(source?.data.binding!==IAM_PRINCIPAL_BINDING || source.data.provider!=='tools' || source.data.origin!=='existing' || !(target?.foundation&&S3_ACCESS_MODES.includes(edge.access) || (target?.compute||target?.summary)&&edge.access==='lambda-invoke' || target?.api&&edge.access==='api-invoke'))return [];
+  return [{id:edge.id,source:edge.source,target:edge.target,access:edge.access,principalVariable:`principal_${resources.get(edge.source).address}_arn`}];
+ });
+ const bindings=[...new Set(connections.map(e=>e.source))].map(id=>({id,variable:`principal_${resources.get(id).address}_arn`}));
+ return {connections,bindings};
+}

package/src/source-contracts.mjs

@@ -0,0 +1,17 @@
+import sources from './runtime/rag-sources.json' with {type:'json'};
+export function sourceContractPlan(project,rows,retrievalPlan){
+ const catalogs=new Set(retrievalPlan.entries.map(e=>e.table.id)),byId=new Map(rows.map(r=>[r.id,r]));
+ const sources=project.nodes.filter(n=>n.data.origin==='existing'&&n.data.provider==='tools'&&n.data.binding==='normalized-source-contract');
+ const connections=project.edges.filter(e=>e.integration==='source-catalog-sync'&&catalogs.has(e.target)&&sources.some(n=>n.id===e.source));
+ return {sources:sources.filter(n=>connections.some(e=>e.source===n.id)).map(n=>byId.get(n.id)),connections};
+}
+export function sourceContractFiles(plan){
+ if(!plan.sourceContractPlan.sources.length)return {};
+ const files={};
+ const runtime=plan.ragPlan.entries[0].worker.address;
+ files['app-tests/connector_contract_test.py']=`import sys\nfrom pathlib import Path\nsys.path.insert(0,str(Path(__file__).resolve().parents[1]/"build/${runtime}"))\n`+sources['connector_acceptance.py'];
+ for(const name of ['catalog_admin.py','connector_sync.py','connector_cli.py'])files[`connectors/${name}`]=sources[name];
+ files['connectors/sources.json']=JSON.stringify(plan.sourceContractPlan.sources.map(s=>({sourceId:s.address,system:s.label,protocol:'normalized-snapshot-v1',vendorCompatibility:'not_verified',credential:'ATMEM_SOURCE_TOKEN environment variable; never a diagram/config secret',targetCatalogIds:plan.sourceContractPlan.connections.filter(e=>e.source===s.id).map(e=>e.target)})),null,2);
+ files['connectors/CONTRACT.md']='# Local source-contract qualification\n\nThese adapters consume a normalized snapshot contract from explicitly configured endpoints. They are not native Microsoft Graph or Confluence REST adapters. SharePoint/Confluence permission mapping, group expansion, inherited restrictions, API paging and tenant authentication must be independently qualified before real integration. Local fixtures prove this contract only.\n\nAn endpoint returns snapshotId, complete=true, permissionsComplete=true and documents (maximum 100). Each document supplies sourceId, sourceVersion, title, text, allowedSubjects and allowedRegions. The entire snapshot must be complete before publishing; missing entries are deletions. Unknown or incomplete permissions fail closed. Redirects are refused; HTTPS is required except with the explicit loopback fixture option. Credentials come from ATMEM_SOURCE_TOKEN.\n\nRun connector_cli.py with the exact source ID in sources.json, reviewed endpoint/catalog/account/region, a private checkpoint path and --confirm-sync. It journals pending inventory before writes and commits after reconciliation. Retry from the same checkpoint after failure; conditional revisions prevent blind overwrites. Use one designated sync runner per source. A local lock prevents overlapping runs; review a stale lock after a crash rather than blindly deleting it.\n\nSource-derived document access expires after 60 seconds unless refreshed by a complete authorized snapshot. Refresh more often than the lease, monitor failures and test timing. Expired documents are excluded before model invocation and response delivery. This favors access revocation over stale-source availability. Do not remove the lease to make outage tests pass.\n';
+ return files;
+}