@atmem/architect 0.0.0-stage → 0.2.0

package/src/runtime/enterprise_document_job.py

@@ -0,0 +1,109 @@
+"""One-file mounted job transport; never write source or result text to logs.
+
+The launcher owns two distinct per-file mounts: read-only /input and writable
+/output. This protocol is not a sandbox. Native workloads must separately remove
+credentials, contain network/processes, bound resources and delete both mounts.
+"""
+import hashlib
+import json
+import os
+import re
+import stat
+import uuid
+from enterprise_document_contract import MAX_INPUT, MAX_TEXT, ExtractionError, document_result, media_type
+
+MAX_ENVELOPE = MAX_TEXT * 6 + 4096
+
+
+def unique(pairs):
+    value = {}
+    for key, item in pairs:
+        if key in value: raise ExtractionError('invalid_document')
+        value[key] = item
+    return value
+
+
+def request(raw, declared, request_id):
+    if (not isinstance(raw, bytes) or not 0 < len(raw) <= MAX_INPUT or
+        not isinstance(request_id, str) or not re.fullmatch('[0-9a-f]{64}', request_id)):
+        raise ExtractionError('invalid_document')
+    return {'format': 'enterprise-document-job-v1', 'requestId': request_id,
+            'sha256': hashlib.sha256(raw).hexdigest(), 'mediaType': media_type(declared)}
+
+
+def result(raw, declared, request_id, encoded):
+    """Consumer check after the isolated job exits successfully, before caching."""
+    expected = request(raw, declared, request_id)
+    if not isinstance(encoded, bytes) or not 0 < len(encoded) <= MAX_ENVELOPE:
+        raise ExtractionError('invalid_document')
+    try:
+        value = json.loads(encoded, object_pairs_hook=unique)
+        if (not isinstance(value, dict) or set(value) != {'format', 'requestId', 'status', 'document'} or
+            value['format'] != expected['format'] or value['requestId'] != request_id or value['status'] != 'ok'):
+            raise ValueError()
+        return document_result(value['document'], raw, expected['mediaType'])
+    except Exception:
+        raise ExtractionError('invalid_document') from None
+
+
+def read_file(directory_fd, name, limit):
+    fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory_fd)
+    with os.fdopen(fd, 'rb') as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or not 0 < info.st_size <= limit:
+            raise ExtractionError('invalid_document')
+        raw = stream.read(limit + 1)
+        if not 0 < len(raw) <= limit or len(raw) != info.st_size:
+            raise ExtractionError('invalid_document')
+        return raw
+
+
+def write_result(directory_fd, value):
+    # Exclusive publication refuses an old/stale output and any symlink target.
+    # The launcher consumes only after successful process exit; a crashed partial
+    # temporary file cannot look like a complete result.
+    encoded = json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(',', ':')).encode()
+    if len(encoded) > MAX_ENVELOPE: raise ExtractionError('extraction_failed')
+    temporary = '.result-' + uuid.uuid4().hex
+    try:
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory_fd)
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(encoded)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.link(temporary, 'result.json', src_dir_fd=directory_fd, dst_dir_fd=directory_fd, follow_symlinks=False)
+        os.fsync(directory_fd)
+    finally:
+        try: os.unlink(temporary, dir_fd=directory_fd)
+        except FileNotFoundError: pass
+
+
+def execute(parser, input_path='/input', output_path='/output'):
+    """Extract one document using fixed mount paths; errors contain no input data."""
+    source = target = None
+    try:
+        source = os.open(input_path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        target = os.open(output_path, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        left, right = os.fstat(source), os.fstat(target)
+        if (left.st_dev, left.st_ino) == (right.st_dev, right.st_ino):
+            raise ExtractionError('invalid_document')
+        # Do not parse if the destination already exists (including a symlink).
+        try: os.stat('result.json', dir_fd=target, follow_symlinks=False)
+        except FileNotFoundError: pass
+        else: raise ExtractionError('invalid_document')
+        metadata = json.loads(read_file(source, 'request.json', 2048), object_pairs_hook=unique)
+        raw = read_file(source, 'document', MAX_INPUT)
+        if not isinstance(metadata, dict) or set(metadata) != {'format', 'requestId', 'sha256', 'mediaType'}:
+            raise ExtractionError('invalid_document')
+        expected = request(raw, metadata['mediaType'], metadata['requestId'])
+        if metadata != expected: raise ExtractionError('invalid_document')
+        document = document_result(parser.extract(raw, expected['mediaType']), raw, expected['mediaType'])
+        write_result(target, {'format': expected['format'], 'requestId': expected['requestId'], 'status': 'ok', 'document': document})
+        return {'status': 'ok'}, 0
+    except ExtractionError as failure:
+        return {'status': 'rejected', 'reason': failure.code}, 2
+    except Exception:
+        return {'status': 'rejected', 'reason': 'extraction_unavailable'}, 2
+    finally:
+        for fd in (target, source):
+            if fd is not None: os.close(fd)

package/src/runtime/enterprise_document_jobs.py

@@ -0,0 +1,122 @@
+"""Durable per-file cleanup intents, fencing and uncertain-creation settlement.
+
+No source payload, title, identity, question, credential, endpoint or error body is
+stored. Cleanup targets are derived by the owned adapter, never interpreted from
+database text. All transactions end before native API work begins.
+"""
+from dataclasses import dataclass, field
+import hashlib
+from pathlib import Path
+import re
+import uuid
+from psycopg import sql
+from enterprise_sources import SourceUnavailable
+
+
+@dataclass(frozen=True)
+class FileJobLease:
+    request_id: str
+    token: str = field(repr=False)
+
+
+class DocumentJobLedger:
+    def __init__(self, auth, account_id, target_sha256):
+        if not isinstance(account_id, str) or not re.fullmatch('[A-Za-z0-9_-]{1,128}', account_id): raise ValueError('Use the owned company account')
+        if not isinstance(target_sha256, str) or not re.fullmatch('[0-9a-f]{64}', target_sha256): raise ValueError('Use the owned immutable cleanup target')
+        self.auth, self.account_id, self.target = auth, account_id, target_sha256
+        with auth.transaction() as cursor:
+            expected=hashlib.sha256(Path(__file__).with_name('enterprise_document_jobs_schema.sql').read_bytes()).hexdigest()
+            if cursor.execute('SELECT version,source_sha256 FROM enterprise_document_jobs.schema_version').fetchone()!={'version':1,'source_sha256':expected}:
+                raise SourceUnavailable('document_job_schema_changed')
+
+    def parameters(self, identifier):
+        if not isinstance(identifier, str) or not re.fullmatch('[0-9a-f]{64}', identifier): raise ValueError('Use the owned per-file request')
+        return self.account_id, self.target, identifier
+
+    def allocate(self, identifier, *, ttl_seconds=240):
+        if type(ttl_seconds) is not int or not 180 <= ttl_seconds <= 600: raise ValueError('Use a bounded active execution deadline')
+        token = str(uuid.uuid4()); values = self.parameters(identifier)
+        with self.auth.transaction() as cursor:
+            self.auth.require_company(cursor, self.account_id)
+            row = cursor.execute("INSERT INTO enterprise_document_jobs.jobs(account_id,target_sha256,request_id,owner_token,phase,state,expires_at,next_attempt_at)VALUES(%s,%s,%s,%s,'input_pending','active',clock_timestamp()+make_interval(secs=>%s),clock_timestamp())ON CONFLICT DO NOTHING RETURNING request_id", (*values, token, ttl_seconds)).fetchone()
+            if not row: raise SourceUnavailable('document_execution_identity_conflict')
+        return FileJobLease(identifier, token)
+
+    def active(self, cursor, lease, *, lock=False):
+        row = cursor.execute("SELECT *,expires_at>clock_timestamp()AS current FROM enterprise_document_jobs.jobs WHERE account_id=%s AND target_sha256=%s AND request_id=%s" + (' FOR UPDATE' if lock else ''), self.parameters(lease.request_id)).fetchone()
+        if not row or row['state'] != 'active' or str(row['owner_token']) != lease.token or not row['current']:
+            raise SourceUnavailable('document_execution_lease_changed')
+        return row
+
+    def guard(self, lease):
+        with self.auth.transaction() as cursor: self.active(cursor, lease)
+
+    def advance(self, lease, phase):
+        previous = {'job_pending': 'input_pending', 'job_running': 'job_pending', 'succeeded': 'job_running'}
+        if phase not in previous: raise ValueError('Use the owned monotonic execution phases')
+        with self.auth.transaction() as cursor:
+            row = self.active(cursor, lease, lock=True)
+            if row['phase'] not in {previous[phase], phase}: raise SourceUnavailable('document_execution_phase_changed')
+            cursor.execute('UPDATE enterprise_document_jobs.jobs SET phase=%s,updated_at=clock_timestamp()WHERE account_id=%s AND target_sha256=%s AND request_id=%s', (phase, *self.parameters(lease.request_id)))
+
+    def mark_cleaning(self, cursor, identifier):
+        token = str(uuid.uuid4())
+        cursor.execute("UPDATE enterprise_document_jobs.jobs SET state='cleaning',cleanup_token=%s,cleanup_until=clock_timestamp()+interval '180 seconds',updated_at=clock_timestamp()WHERE account_id=%s AND target_sha256=%s AND request_id=%s", (token, *self.parameters(identifier)))
+        return FileJobLease(identifier, token)
+
+    def claim_owner(self, lease):
+        with self.auth.transaction() as cursor:
+            row = cursor.execute('SELECT *,cleanup_until>clock_timestamp()AS leased FROM enterprise_document_jobs.jobs WHERE account_id=%s AND target_sha256=%s AND request_id=%s FOR UPDATE', self.parameters(lease.request_id)).fetchone()
+            if not row or str(row['owner_token']) != lease.token or row['state'] != 'active': raise SourceUnavailable('document_execution_lease_changed')
+            return self.mark_cleaning(cursor, lease.request_id)
+
+    def claim_due(self):
+        with self.auth.transaction() as cursor:
+            row = cursor.execute("SELECT request_id FROM enterprise_document_jobs.jobs WHERE account_id=%s AND target_sha256=%s AND((state='active'AND expires_at<clock_timestamp())OR(state IN('pending','settling')AND next_attempt_at<=clock_timestamp())OR(state='cleaning'AND cleanup_until<clock_timestamp()))ORDER BY updated_at FOR UPDATE SKIP LOCKED LIMIT 1", (self.account_id, self.target)).fetchone()
+            return self.mark_cleaning(cursor, row['request_id']) if row else None
+
+    def cleanup_row(self, cursor, lease):
+        row = cursor.execute('SELECT *,cleanup_until>clock_timestamp()AS leased FROM enterprise_document_jobs.jobs WHERE account_id=%s AND target_sha256=%s AND request_id=%s FOR UPDATE', self.parameters(lease.request_id)).fetchone()
+        if not row or row['state'] != 'cleaning' or str(row['cleanup_token']) != lease.token or not row['leased']:
+            raise SourceUnavailable('document_cleanup_lease_changed')
+        return row
+
+    def completed(self, lease):
+        with self.auth.transaction() as cursor:
+            row = self.cleanup_row(cursor, lease)
+            final = row['phase'] == 'succeeded' or (row['settle_until'] is not None and cursor.execute('SELECT %s<=clock_timestamp()AS done', (row['settle_until'],)).fetchone()['done'])
+            if final:
+                cursor.execute('DELETE FROM enterprise_document_jobs.jobs WHERE account_id=%s AND target_sha256=%s AND request_id=%s', self.parameters(lease.request_id))
+                return True
+            # Retain incomplete/uncertain creations for delayed cleanup probes.
+            # These are scheduling bounds, not a provider deletion/retention SLA.
+            delay = [60, 300, 1800, 86400][min(row['settle_round'], 3)]
+            cursor.execute("UPDATE enterprise_document_jobs.jobs SET state='settling',cleanup_token=NULL,cleanup_until=NULL,settle_until=coalesce(settle_until,clock_timestamp()+interval '24 hours'),settle_round=least(settle_round+1,4),next_attempt_at=least(clock_timestamp()+make_interval(secs=>%s),coalesce(settle_until,clock_timestamp()+interval '24 hours')),updated_at=clock_timestamp()WHERE account_id=%s AND target_sha256=%s AND request_id=%s", (delay, *self.parameters(lease.request_id)))
+            return False
+
+    def failed(self, lease):
+        with self.auth.transaction() as cursor:
+            row = self.cleanup_row(cursor, lease)
+            delay = min(600, 30 * 2 ** min(row['failures'], 5))
+            cursor.execute("UPDATE enterprise_document_jobs.jobs SET state='pending',cleanup_token=NULL,cleanup_until=NULL,failures=least(failures+1,1000000),next_attempt_at=clock_timestamp()+make_interval(secs=>%s),updated_at=clock_timestamp()WHERE account_id=%s AND target_sha256=%s AND request_id=%s", (delay, *self.parameters(lease.request_id)))
+
+
+def initialize_document_jobs(conn):
+    if conn.autocommit: raise ValueError('Use an owned operator transaction')
+    raw = Path(__file__).with_name('enterprise_document_jobs_schema.sql').read_bytes()
+    conn.execute(raw.decode()); conn.execute('INSERT INTO enterprise_document_jobs.schema_version VALUES(1,%s)', (hashlib.sha256(raw).hexdigest(),))
+
+
+def grant_document_jobs_runtime(conn, role):
+    if conn.autocommit or not isinstance(role, str) or not re.fullmatch('[A-Za-z0-9_.@-]{1,63}', role): raise ValueError('Use an owned worker identity and operator transaction')
+    expected = hashlib.sha256(Path(__file__).with_name('enterprise_document_jobs_schema.sql').read_bytes()).hexdigest()
+    if conn.execute('SELECT version,source_sha256 FROM enterprise_document_jobs.schema_version').fetchone() != (1, expected): raise ValueError('Review the exact fresh document-job schema')
+    flags = conn.execute('SELECT rolsuper,rolcreatedb,rolcreaterole,rolreplication,rolbypassrls,rolcanlogin FROM pg_roles WHERE rolname=%s', (role,)).fetchone()
+    if not flags or any(flags[:5]) or not flags[5] or conn.execute("SELECT has_schema_privilege(%s,'enterprise_document_jobs','CREATE')", (role,)).fetchone()[0]: raise ValueError('Use a nonadministrative worker identity')
+    for table in ['memberships', 'source_mappings', 'company_bindings', 'schema_version']:
+        if conn.execute('SELECT has_table_privilege(%s,%s,%s)', (role, 'enterprise_auth.' + table, 'INSERT,UPDATE,DELETE,TRUNCATE,TRIGGER,REFERENCES')).fetchone()[0]: raise ValueError('Document worker must not inherit company authority writes')
+    if conn.execute("SELECT has_table_privilege(%s,'enterprise_document_jobs.jobs','TRUNCATE,TRIGGER,REFERENCES')", (role,)).fetchone()[0]: raise ValueError('Document worker must not inherit administrative cleanup privileges')
+    target = sql.Identifier(role)
+    conn.execute(sql.SQL('GRANT USAGE ON SCHEMA enterprise_document_jobs TO {}').format(target))
+    conn.execute(sql.SQL('GRANT SELECT ON enterprise_document_jobs.schema_version TO {}').format(target))
+    conn.execute(sql.SQL('GRANT SELECT,INSERT,UPDATE,DELETE ON enterprise_document_jobs.jobs TO {}').format(target))

package/src/runtime/enterprise_document_jobs_schema.sql

@@ -0,0 +1,23 @@
+-- Fresh installation only; metadata-only cleanup intent, never document content.
+CREATE SCHEMA enterprise_document_jobs;
+REVOKE ALL ON SCHEMA enterprise_document_jobs FROM PUBLIC;
+CREATE TABLE enterprise_document_jobs.schema_version(
+ version integer PRIMARY KEY CHECK(version=1),source_sha256 text NOT NULL
+);
+CREATE TABLE enterprise_document_jobs.jobs(
+ account_id text NOT NULL REFERENCES enterprise_auth.company_bindings(account_id),
+ target_sha256 text NOT NULL CHECK(target_sha256 ~ '^[0-9a-f]{64}$'),
+ request_id text NOT NULL CHECK(request_id ~ '^[0-9a-f]{64}$'),
+ owner_token uuid NOT NULL,
+ phase text NOT NULL CHECK(phase IN('input_pending','job_pending','job_running','succeeded')),
+ state text NOT NULL CHECK(state IN('active','cleaning','pending','settling')),
+ expires_at timestamptz NOT NULL,next_attempt_at timestamptz NOT NULL,
+ cleanup_token uuid,cleanup_until timestamptz,
+ failures integer NOT NULL DEFAULT 0 CHECK(failures BETWEEN 0 AND 1000000),
+ settle_until timestamptz,settle_round integer NOT NULL DEFAULT 0 CHECK(settle_round BETWEEN 0 AND 4),
+ created_at timestamptz NOT NULL DEFAULT clock_timestamp(),updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+ PRIMARY KEY(account_id,target_sha256,request_id),
+ CHECK((state='cleaning')=(cleanup_token IS NOT NULL AND cleanup_until IS NOT NULL))
+);
+CREATE INDEX enterprise_document_jobs_due ON enterprise_document_jobs.jobs(account_id,target_sha256,state,next_attempt_at,expires_at);
+REVOKE ALL ON ALL TABLES IN SCHEMA enterprise_document_jobs FROM PUBLIC;

package/src/runtime/enterprise_extraction_cache.py

@@ -0,0 +1,186 @@
+"""Encrypted immutable-byte extraction reuse, never cached source authorization.
+
+Only a native source adapter can invoke ``from_source`` with its live version/access
+check. Every hit still requires newly authorized source bytes. Native source and
+company/job checks surround reads, extraction, publication and return. No source
+URL, private title, user identity or credential is stored in the cache.
+"""
+from contextlib import contextmanager
+import hashlib
+from pathlib import Path
+import re
+import time
+import uuid
+from psycopg import sql
+from enterprise_document_contract import MAX_INPUT, MAX_TEXT, media_type
+from enterprise_sources import SourceUnavailable
+
+
+class ExtractionLeaseLost(SourceUnavailable):
+    pass
+
+
+def checked_text(value):
+    if not isinstance(value, str) or not value.strip() or '\x00' in value:
+        raise SourceUnavailable('document_extraction_unavailable')
+    try:
+        if len(value.encode('utf-8')) > MAX_TEXT:
+            raise ValueError()
+    except (ValueError, UnicodeError):
+        raise SourceUnavailable('document_extraction_unavailable') from None
+    return value
+
+
+class ExtractionCache:
+    def __init__(self, auth, account_id, parser_revision, *, ttl_seconds=900, lease_seconds=150, wait_seconds=160):
+        if not isinstance(account_id, str) or not re.fullmatch('[A-Za-z0-9_-]{1,128}', account_id):
+            raise ValueError('Supply the owned company account')
+        if not isinstance(parser_revision, str) or not re.fullmatch('[0-9a-f]{64}', parser_revision):
+            raise ValueError('Supply the reviewed complete parser artifact revision')
+        if (type(ttl_seconds) is not int or not 60 <= ttl_seconds <= 3600
+            or type(lease_seconds) is not int or not 15 <= lease_seconds <= 300
+            or type(wait_seconds) is not int or not 1 <= wait_seconds <= 600):
+            raise ValueError('Use bounded owned cache deadlines')
+        self.auth, self.account_id, self.parser_revision = auth, account_id, parser_revision
+        self.ttl_seconds, self.lease_seconds, self.wait_seconds = ttl_seconds, lease_seconds, wait_seconds
+
+    @contextmanager
+    def transaction(self):
+        with self.auth.transaction() as cur:
+            cur.execute('SET LOCAL search_path=pg_catalog,enterprise_extractions,pg_temp')
+            yield cur
+
+    def identity(self, raw, declared):
+        if not isinstance(raw, bytes) or not 0 < len(raw) <= MAX_INPUT:
+            raise SourceUnavailable('source_document_unsupported')
+        try:
+            mime = media_type(declared)
+        except Exception:
+            raise SourceUnavailable('source_document_unsupported') from None
+        digest = hashlib.sha256(raw).hexdigest()
+        key = self.auth.box.fingerprint(['document-extraction-cache', self.account_id, self.parser_revision, mime], digest)
+        return key, digest, mime
+
+    def context(self, key):
+        return ['document-extraction-cache', self.account_id, self.parser_revision, key]
+
+    def claim(self, key):
+        """Brief transaction only; parser/network work never holds SQL row locks."""
+        with self.transaction() as cur:
+            token = str(uuid.uuid4())
+            cur.execute("INSERT INTO enterprise_extractions.documents(account_id,parser_revision,content_key,state,lease_token,lease_until,expires_at)VALUES(%s,%s,%s,'building',%s,clock_timestamp()+make_interval(secs=>%s),clock_timestamp()+make_interval(secs=>%s))ON CONFLICT DO NOTHING",
+                (self.account_id, self.parser_revision, key, token, self.lease_seconds, self.lease_seconds))
+            row = cur.execute('SELECT *,expires_at>clock_timestamp()AS current,lease_until>clock_timestamp()AS leased FROM enterprise_extractions.documents WHERE account_id=%s AND parser_revision=%s AND content_key=%s FOR UPDATE',
+                (self.account_id, self.parser_revision, key)).fetchone()
+            if row['state'] == 'ready' and row['current']:
+                return 'ready', row['value_ciphertext']
+            if row['state'] == 'building' and row['leased']:
+                return ('claimed', token) if str(row['lease_token']) == token else ('waiting', None)
+            cur.execute("UPDATE enterprise_extractions.documents SET state='building',value_ciphertext=NULL,lease_token=%s,lease_until=clock_timestamp()+make_interval(secs=>%s),expires_at=clock_timestamp()+make_interval(secs=>%s)WHERE account_id=%s AND parser_revision=%s AND content_key=%s",
+                (token, self.lease_seconds, self.lease_seconds, self.account_id, self.parser_revision, key))
+            return 'claimed', token
+
+    def publish(self, key, token, value):
+        cipher = self.auth.box.seal(self.context(key), value)
+        with self.transaction() as cur:
+            row = cur.execute("UPDATE enterprise_extractions.documents SET state='ready',lease_token=NULL,lease_until=NULL,value_ciphertext=%s,expires_at=clock_timestamp()+make_interval(secs=>%s)WHERE account_id=%s AND parser_revision=%s AND content_key=%s AND state='building'AND lease_token=%s AND lease_until>clock_timestamp()RETURNING content_key",
+                (cipher, self.ttl_seconds, self.account_id, self.parser_revision, key, token)).fetchone()
+            if not row:
+                raise ExtractionLeaseLost('document_extraction_lease_changed')
+
+    def abandon(self, key, token):
+        with self.transaction() as cur:
+            cur.execute("DELETE FROM enterprise_extractions.documents WHERE account_id=%s AND parser_revision=%s AND content_key=%s AND state='building'AND lease_token=%s",
+                (self.account_id, self.parser_revision, key, token))
+
+    def open(self, key, digest, mime, cipher):
+        value = self.auth.box.open(self.context(key), cipher)
+        if set(value) != {'sha256', 'mediaType', 'text'} or value['sha256'] != digest or value['mediaType'] != mime:
+            raise SourceUnavailable('document_extraction_binding_invalid')
+        return checked_text(value['text'])
+
+    def wrap(self, extract, authorize):
+        if not callable(extract) or not callable(authorize):
+            raise ValueError('Supply owned extraction and live company/job authority')
+        return CachedDecoder(self, extract, authorize)
+
+    def purge(self, limit=1000):
+        if type(limit) is not int or not 1 <= limit <= 5000:
+            raise ValueError('Use a bounded expiration batch')
+        with self.transaction() as cur:
+            rows = cur.execute('DELETE FROM enterprise_extractions.documents WHERE(account_id,parser_revision,content_key)IN(SELECT account_id,parser_revision,content_key FROM enterprise_extractions.documents WHERE account_id=%s AND expires_at<clock_timestamp()ORDER BY expires_at FOR UPDATE SKIP LOCKED LIMIT %s)RETURNING content_key',
+                (self.account_id, limit)).fetchall()
+            return len(rows)
+
+
+class CachedDecoder:
+    def __init__(self, cache, extract, authorize):
+        self.cache, self.extract, self.authorize = cache, extract, authorize
+
+    def __call__(self, raw, declared):
+        # A plain callback does not prove the surrounding native source has a live
+        # authorization/version check. Unreviewed adapters must not bypass it.
+        raise SourceUnavailable('source_validation_required')
+
+    def from_source(self, raw, declared, revalidate):
+        if not callable(revalidate):
+            raise ValueError('Supply the native live source check')
+        key, digest, mime = self.cache.identity(raw, declared)
+        deadline = time.monotonic() + self.cache.wait_seconds
+        def guard():
+            self.authorize()
+            revalidate()
+        guard()
+        while True:
+            self.authorize()
+            state, material = self.cache.claim(key)
+            if state == 'ready':
+                guard()
+                text = self.cache.open(key, digest, mime, material)
+                guard()
+                return text
+            if state == 'claimed':
+                try:
+                    guard()
+                    # A native per-file launcher must recheck authority while
+                    # waiting and before releasing input/results, not only after
+                    # a potentially slow cloud execution has already finished.
+                    owned = getattr(self.extract, 'from_source', None)
+                    text = checked_text(owned(raw, mime, guard) if callable(owned) else self.extract(raw, mime))
+                    guard()
+                    self.cache.publish(key, material, {'sha256': digest, 'mediaType': mime, 'text': text})
+                    guard()
+                    return text
+                except BaseException:
+                    # A failed/denied/stale extractor never replaces a newer row.
+                    self.cache.abandon(key, material)
+                    raise
+            if time.monotonic() >= deadline:
+                raise SourceUnavailable('document_extraction_busy')
+            time.sleep(min(.2, max(0, deadline - time.monotonic())))
+
+
+def initialize_extraction_cache(conn):
+    if conn.autocommit:
+        raise ValueError('Use an owned operator transaction')
+    source = Path(__file__).with_name('enterprise_extraction_schema.sql').read_bytes()
+    conn.execute(source.decode())
+    conn.execute('INSERT INTO enterprise_extractions.schema_version VALUES(1,%s)', (hashlib.sha256(source).hexdigest(),))
+
+
+def grant_extraction_runtime(conn, role):
+    if conn.autocommit or not isinstance(role, str) or not re.fullmatch('[A-Za-z0-9_.@-]{1,63}', role):
+        raise ValueError('Use an owned nonadministrative runtime role and operator transaction')
+    expected = hashlib.sha256(Path(__file__).with_name('enterprise_extraction_schema.sql').read_bytes()).hexdigest()
+    if conn.execute('SELECT version,source_sha256 FROM enterprise_extractions.schema_version').fetchone() != (1, expected):
+        raise ValueError('Review the exact fresh cache schema before granting access')
+    flags = conn.execute('SELECT rolsuper,rolcreatedb,rolcreaterole,rolreplication,rolbypassrls,rolcanlogin FROM pg_roles WHERE rolname=%s', (role,)).fetchone()
+    if not flags or any(flags[:5]) or not flags[5] or conn.execute("SELECT has_schema_privilege(%s,'enterprise_extractions','CREATE')", (role,)).fetchone()[0]:
+        raise ValueError('Use a nonadministrative role that does not own the cache schema')
+    for table in ['memberships', 'source_mappings', 'company_bindings', 'schema_version']:
+        if conn.execute('SELECT has_table_privilege(%s,%s,%s)', (role, 'enterprise_auth.' + table, 'INSERT,UPDATE,DELETE,TRUNCATE,TRIGGER,REFERENCES')).fetchone()[0]:
+            raise ValueError('Cache runtime must not inherit authority-table write privileges')
+    target = sql.Identifier(role)
+    conn.execute(sql.SQL('GRANT USAGE ON SCHEMA enterprise_extractions TO {}').format(target))
+    conn.execute(sql.SQL('GRANT SELECT ON enterprise_extractions.schema_version TO {}').format(target))
+    conn.execute(sql.SQL('GRANT SELECT,INSERT,UPDATE,DELETE ON enterprise_extractions.documents TO {}').format(target))

package/src/runtime/enterprise_extraction_schema.sql

@@ -0,0 +1,17 @@
+-- Fresh owned installation only; cached derivatives are not source authority.
+CREATE SCHEMA enterprise_extractions;
+REVOKE ALL ON SCHEMA enterprise_extractions FROM PUBLIC;
+CREATE TABLE enterprise_extractions.schema_version(
+ version integer PRIMARY KEY CHECK(version=1),source_sha256 text NOT NULL
+);
+CREATE TABLE enterprise_extractions.documents(
+ account_id text NOT NULL,parser_revision text NOT NULL CHECK(parser_revision ~ '^[0-9a-f]{64}$'),
+ content_key text NOT NULL CHECK(content_key ~ '^[0-9a-f]{64}$'),
+ state text NOT NULL CHECK(state IN('building','ready')),
+ lease_token uuid,lease_until timestamptz,value_ciphertext text,expires_at timestamptz NOT NULL,
+ PRIMARY KEY(account_id,parser_revision,content_key),
+ CHECK((state='ready')=(value_ciphertext IS NOT NULL)),
+ CHECK((state='building')=(lease_token IS NOT NULL AND lease_until IS NOT NULL))
+);
+CREATE INDEX enterprise_extractions_expiry ON enterprise_extractions.documents(account_id,expires_at);
+REVOKE ALL ON ALL TABLES IN SCHEMA enterprise_extractions FROM PUBLIC;