diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 2afce57d..abd78b0a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -61,6 +61,11 @@ jobs: - run: node tests/browser_scientific_fields.cjs env: BROWSER: /usr/bin/google-chrome + - run: node --check static/workspace-external.js + - run: node tests/test_workspace_external_controller.cjs + - run: node tests/browser_workspace_external.cjs + env: + BROWSER: /usr/bin/google-chrome - run: node --check static/workspace-projects.js - run: node tests/browser_workspace_project.cjs env: diff --git a/README.md b/README.md index 2fb32657..9d235c45 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ current record; saving/reviewing and freezing a new release leaves old results unchanged. Viewing test results records durable exposure; reused records or pixels cannot be presented as fresh holdout evidence. -Fresh catalogs use schema 7. Existing PostgreSQL schema-1 through schema-6 catalogs require an +Fresh catalogs use schema 8. Existing PostgreSQL schema-1 through schema-7 catalogs require an explicit stopped-writer backup and upgrade, never an automatic startup change: ```sh @@ -92,6 +92,19 @@ finishes. See [workspace storage](docs/contracts/workspace-storage.md), [CPU adapter](docs/contracts/workspace-image-training.md) for bounds and recovery. The original corner studio and classic Workbench remain available. +## Approved local recipes + +A project can declare an exact local Python recipe with typed parameters, named +inputs and bounded output files. In Pipeline, select its recipe, edit/save the +graph, review preflight and approve the exact execution. Runs shows durable state, +cancellation and verified output downloads. Owners can issue one-use approvals +for explicitly scoped agents. These are trusted same-user programs with ordinary +filesystem/network authority, not sandboxed plugins. Missing drainage after a +custodian failure remains unknown and blocks further external execution until +cessation is proven. See the [external recipe contract](docs/contracts/external-recipes.md) +for runtime support, limits and recovery. Scientific generation/training remains +separately qualified; neutral executable tests are not model acceptance. + ## Text classification and WAV data The same optional CPU environment supports a bounded **TF-IDF / MultinomialNB** diff --git a/access.py b/access.py index 6b04d748..2ae09b56 100644 --- a/access.py +++ b/access.py @@ -19,6 +19,7 @@ SESSION_TTL = 8 * 3600 LOGIN_TTL = 600 MAX_TOKEN_TTL = 30 * 86400 +MAX_APPROVAL_TTL = 3600 _CURRENT = ContextVar('tuldok_actor', default=None) HASH = re.compile(r'^[a-f0-9]{64}$') @@ -333,6 +334,103 @@ def admit_job(self, kind, job_id, request_digest, effects): self.audit('access.admit_job', job_id, {'admission_id': admission_id, 'kind': kind, 'request_digest': request_digest, 'effects': effects}) return admission_id + def require_external_submission(self): + """Check only the dedicated approved external-Run entrypoint. + + This is not an execution grant: admission additionally requires atomic + consumption of an exact material/actor approval. Ordinary execute + guards and job admission remain owner-only. + """ + try: + with self.lock: + context = self.require('inspect', 'runs.external_submit') + if context.mode != 'credential': + raise AccessError('External submission requires a live credential.') + row = self._credential(context.credential_id) + if 'execute' not in json.loads(row['scopes_json']): + raise AccessError('External submission requires execute scope.') + return context + except AccessError as error: + self.denial(error, 'runs.external_submit') + raise + + @authorized('approve-execution', 'access.grant_execution', owner_only=True) + def grant_execution(self, material_sha256, consumer_actor_id, ttl_seconds=600): + """Approve an already reviewed material digest; Runs owns its meaning.""" + if type(material_sha256) is not str or not HASH.fullmatch(material_sha256): + raise AccessError('Reviewed material digest must be SHA256.', 'invalid', 400) + _text(consumer_actor_id, 'Consuming actor ID') + if type(ttl_seconds) is not int or not 60 <= ttl_seconds <= MAX_APPROVAL_TTL: + raise AccessError('Approval lifetime must be 60 through 3600 seconds.', 'invalid', 400) + with self.lock, self.db.transaction(): + context = self.require('approve-execution', 'access.grant_execution', owner_only=True) + if self.db.execute('SELECT id FROM access_actors WHERE id=%s', (consumer_actor_id,)).fetchone() is None: + raise AccessError('Consuming actor does not belong to this catalog.', 'unavailable', 404) + created = int(time.time()) + grant = dict(id=uuid.uuid4().hex, catalog_id=self.catalog_id, + approver_actor_id=context.actor_id, approver_credential_id=context.credential_id, + consumer_actor_id=consumer_actor_id, material_sha256=material_sha256, + created_at=created, expires_at=created + ttl_seconds, revoked_at=None) + self.db.execute('INSERT INTO access_execution_grants VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)', + tuple(grant.values())) + self.audit('access.grant_execution', grant['id'], grant) + return grant + + @authorized('approve-execution', 'access.revoke_execution', owner_only=True) + def revoke_execution(self, grant_id): + _text(grant_id, 'Approval ID') + with self.lock, self.db.transaction(): + row = self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s FOR UPDATE', (grant_id,)).fetchone() + if row is None or row['catalog_id'] != self.catalog_id: + raise AccessError('Execution approval is unavailable.', 'unavailable', 404) + if self.db.execute('SELECT grant_id FROM access_execution_consumptions WHERE grant_id=%s', (grant_id,)).fetchone(): + raise AccessError('Approval was consumed; cancel the admitted Run instead.', 'conflict', 409) + grant = dict(row) + if grant['revoked_at'] is None: + grant['revoked_at'] = int(time.time()) + self.db.execute('UPDATE access_execution_grants SET revoked_at=%s WHERE id=%s', + (grant['revoked_at'], grant_id)) + self.audit('access.revoke_execution', grant_id, {'material_sha256': grant['material_sha256']}) + return grant + + def _consume_external_run(self, grant_id, material_sha256, run_id, request_sha256): + """Consume once alongside the Run insertion in the caller's transaction. + + Runs reconciles its actor/key/request receipt before this call. This + operation never refunds approvals or creates an alternate queue. + """ + if not self.db.in_transaction: + raise RuntimeError('Execution approval consumption requires the Run transaction.') + _text(grant_id, 'Approval ID') + _text(run_id, 'Run ID') + if any(type(value) is not str or not HASH.fullmatch(value) for value in (material_sha256, request_sha256)): + raise AccessError('Material and request digests must be SHA256.', 'invalid', 400) + with self.lock: + context = self.require_external_submission() + grant = self.db.execute('SELECT * FROM access_execution_grants WHERE id=%s FOR UPDATE', (grant_id,)).fetchone() + if grant is None or grant['catalog_id'] != self.catalog_id: + raise AccessError('Execution approval is unavailable.', 'unavailable', 404) + if grant['consumer_actor_id'] != context.actor_id or grant['material_sha256'] != material_sha256: + raise AccessError('Execution approval does not match this actor and reviewed material.') + if grant['revoked_at'] is not None or grant['expires_at'] <= int(time.time()): + raise AccessError('Execution approval is revoked or expired.', 'stale', 409) + if self.db.execute('SELECT grant_id FROM access_execution_consumptions WHERE grant_id=%s', (grant_id,)).fetchone(): + raise AccessError('Execution approval was already consumed.', 'conflict', 409) + # Recheck after the row lock: waiting for a competing consumer must + # not retain stale credential authority. + self.require_external_submission() + admission_id = uuid.uuid4().hex + effects = {'runs.update': [run_id]} + self.db.execute('INSERT INTO access_admissions VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)', + (admission_id, self.catalog_id, context.actor_id, context.credential_id, 'runs', run_id, + request_sha256, _json(effects), int(time.time()))) + self.db.execute('INSERT INTO access_execution_consumptions VALUES (%s,%s,%s,%s,%s,%s)', + (grant_id, run_id, admission_id, context.credential_id, request_sha256, int(time.time()))) + self.audit('access.consume_execution', grant_id, + {'run_id': run_id, 'admission_id': admission_id, 'material_sha256': material_sha256, + 'request_sha256': request_sha256}) + return admission_id + def require_job(self, kind, job_id, admission_id, request_digest): context = self._context() if (context.mode != 'job' or context.kind != kind or context.job_id != job_id diff --git a/app.py b/app.py index 345003db..6c217636 100644 --- a/app.py +++ b/app.py @@ -540,6 +540,9 @@ def do_POST(self): if path.startswith('/api/access/credentials/') and path.endswith('/revoke'): self._access_body() return self.reply(dataset.access.revoke(path.split('/')[-2])) + if path.startswith('/api/access/execution-grants/') and path.endswith('/revoke'): + projects.closed(self._access_body(), ()) + return self.reply(dataset.access.revoke_execution(path.split('/')[-2])) return self._post() except access.AccessError as error: return self._access_error(error) @@ -561,6 +564,9 @@ def _get(self): return self.reply(dataset.projects.get(parts[1])) if len(parts) == 4 and parts[0] == 'projects' and parts[2] == 'evidence': return self.reply(dataset.projects.evidence(parts[1], parts[3])) + if len(parts) == 4 and parts[0] == 'projects' and parts[2] == 'recipes': + query = parse_qs(urlsplit(self.path).query) + return self.reply(dataset.pipelines.inspect_external_recipe(parts[1], parts[3], query.get('expected_sha256', [''])[-1])) if parts == ['context']: return self.reply({'version': 1, 'mode': 'real', 'dataset_id': dataset.db.dataset_id, 'recipe': 'image_classification_v1', 'execution': 'optional_local_cpu'}) @@ -707,6 +713,7 @@ def _get(self): '/workspaces.css': ('workspaces.css', 'text/css'), '/workspaces.js': ('workspaces.js', 'text/javascript'), '/workspace-real.js': ('workspace-real.js', 'text/javascript'), + '/workspace-external.js': ('workspace-external.js', 'text/javascript'), '/workspace-service.js': ('workspace-service.js', 'text/javascript'), '/workspace-fixtures.json': ('workspace-fixtures.json', 'application/json'), '/pipeline-editor.js': ('pipeline-editor.js', 'text/javascript'), @@ -766,6 +773,8 @@ def _post(self): return self.reply(dataset.workbench.scientific.admit(raw, admission, origin), 201) if parts == ['graphs']: return self.reply(dataset.pipelines.create(body), 201) + if parts == ['graphs', 'external']: + return self.reply(dataset.pipelines.create_external(body), 201) if len(parts) == 2 and parts[0] == 'graphs': return self.reply(dataset.pipelines.save(parts[1], body)) if len(parts) == 3 and parts[0] == 'graphs': @@ -773,8 +782,15 @@ def _post(self): return self.reply(dataset.pipelines.clone(parts[1], body), 201) if parts[2] == 'validate': return self.reply(dataset.pipelines.validate(parts[1], body)) + if parts[2] == 'preflight-external': + projects.closed(body, ('revision',)) + return self.reply(dataset.pipelines.preflight_external(parts[1], body['revision'])) if parts == ['runs']: return self.reply(dataset.runs.submit(body), 201) + if parts == ['runs', 'approve-external']: + return self.reply(dataset.runs.approve_external(body), 201) + if parts == ['runs', 'submit-external']: + return self.reply(dataset.runs.submit_external(body), 201) if len(parts) == 3 and parts[0] == 'runs': if parts[2] == 'cancel': return self.reply(dataset.runs.cancel(parts[1])) diff --git a/docs/contracts/actors.md b/docs/contracts/actors.md index 19660632..45c8f50a 100644 --- a/docs/contracts/actors.md +++ b/docs/contracts/actors.md @@ -10,8 +10,9 @@ The owner has inspect, edit, execute, cancel, freeze, approve-review, approve-execution, expose-holdout and admin scopes. An owner may issue an agent bearer with inspect plus selected edit, execute, cancel, freeze and expose-holdout scopes. Agents cannot issue credentials, approve human review or -approve execution. Current execution starts remain owner-only even when an -agent has execute; bounded approved agent execution is deferred to P3b. +approve execution. Existing CPU, integrity and provider execution starts remain owner-only even +when an agent has execute. The dedicated external-Run path below admits an +agent only with a matching one-use material approval. ## Local owner login @@ -71,3 +72,58 @@ revocation/expiry, concurrent one-use exchange, agent scope limits, denial rollback evidence, exact closed receipts, system restrictions, private CLI files and schema-6 upgrade/schema-7 backup restoration. This stage does not claim provider-process containment, approved agent execution or remote deployment. + +## One-use external execution approvals (schema 8) + +`require_external_submission()` checks a live credential with inspect and +execute scopes. It does not grant execution itself. The existing general +execute guards and `admit_job` remain owner-only. Only the dedicated external +Runs owner may compose this check with approval consumption. + +`grant_execution(material_sha256, consumer_actor_id, ttl_seconds=600)` requires +owner approve-execution authority and creates a new immutable grant identity. +The consumer must be an actor in this catalog; TTL is 60–3,600 seconds. Runs +first verifies the exact previously reviewed material digest, which covers the +project/graph, captured source/runtime/input identities, parameters and declared +permissions/resources. Runs retains matching material evidence. Access owns +actor/digest binding and lifetime; it does not interpret recipe semantics. + +`revoke_execution(grant_id)` serializes against consumption by locking the +grant row. Repeating revocation is harmless. A consumed grant cannot be +revoked into reusable authority: cancel its admitted Run instead. Credential +revocation and expiry still deny new submissions independently of grant state. + +`_consume_external_run(grant_id, material_sha256, run_id, request_sha256)` +requires the caller's existing Run transaction. It locks the grant, checks +exact catalog/actor/material, unrevoked/unexpired state and absence of prior +consumption, then rechecks live credential authority after waiting for the +lock. It atomically writes a consumption receipt, an existing-kind `runs` +admission with only `runs.update` for this Run ID, and actor audit evidence. +It returns the admission ID; the caller inserts the Run before committing. +Rollback restores the unused grant. Unknown commit acknowledgement never +refunds it or authorizes another attempt. + +Runs reconciles its existing request key against both consuming actor and exact +request digest before consuming another grant. A matching committed attempt is +returned even after grant expiry; changed actor/digest conflicts. Retry requires +a fresh grant. Owner submit may create and consume its own approval in the +same transaction only against the exact previously reviewed material digest. +Workers use the retained closed admission and may finish bounded effects after +credential revocation; they do not receive approval/admin or owner authority. + +Schema 8 adds `access_execution_grants` and immutable +`access_execution_consumptions`, retaining the exact schema-7 definition. +Complete backups retain unconsumed, revoked and consumed grants with original +expiration and identity. Restoring a pre-consumption backup is a privileged +catalog recovery operation, not a mechanism for refunding live approvals. + +Approval authorizes a launch; it does not establish a sandbox. Same-UID code +retains effective filesystem/network authority unless separately restricted. +Reviewed material must disclose those permissions. Source/runtime capture and +verified descendant drainage establish their specific identity/lifecycle +contracts, not filesystem or network confinement. + +`tests/test_execution_approvals.py` proves exact actor/material matching, +legacy owner-only behavior, TTL/revocation, two-connection consume/revoke races, +transaction rollback, lost commit acknowledgement with retained Run receipt, +closed continuation and schema-7/8 migration/backup custody. diff --git a/docs/contracts/external-recipes.md b/docs/contracts/external-recipes.md new file mode 100644 index 00000000..f38a8301 --- /dev/null +++ b/docs/contracts/external-recipes.md @@ -0,0 +1,133 @@ +# Approved external recipes, version 1 + +Tuldok can execute explicitly reviewed local recipes through the existing Pipeline +and Runs owners. This is trusted same-user code, not a sandbox: it retains the +operating-system user's filesystem, network and reachable-service authority. +Cleared environment variables, scoped API credentials and closed inherited file +descriptors do not constrain that ambient authority. Approve only code whose +actual effects you trust. + +## Definition and graph + +A project recipe reference points to bounded `external_recipe_v1` JSON. It names +an exact source closure, an entrypoint, typed parameters, named captured inputs, +a structured argument vector, declared output roles and limits. Opening and +preflight read data only; they never import project code, run discovery hooks or +install dependencies. Unknown fields, unsupported runtimes, escaping paths, +symlinks and changed hashes fail before execution. + +The first graph has three editable nodes: input → execute → output. It uses the +existing graph store, revision checks, layout and clone operations. Inputs are +actual project data references, not invented frozen-release dependencies. A +changed execution parameter requires a new preflight; layout and name remain +presentation fields. + +The initial `system_python` profile uses `/usr/bin/python3` with `-I -S -B` and a +pinned finite interpreter, standard-library, bytecode and native-library closure. +The installation owner must differ from the app user; files and ancestors cannot +be group/world writable. UID 0 is conventional; this execution container's +read-only installation is mapped to UID 65534. The explicit installed Python +`/etc/pythonX.Y/sitecustomize.py` target is included when referenced. Runtime +immutability is an operational trust assumption, not protection against a host +administrator. Workspace virtualenvs and arbitrary runtime paths are not accepted +by this version. P3b native helper qualification does not silently extend this +public runtime profile. + +Sources and input bytes are captured privately. Bounds are 64 source files, +128 captured files, 64 MiB total captures, 32 parameters and inputs, 32 flat output +names, 64 MiB total outputs and 600 seconds execution. Each declared input is at +most 40 MiB. Arguments are separate tokens, never a shell command. No project +environment overrides are accepted; the effective environment is explicit in +material identity. Runtime inventory is bounded separately at 512 MiB. + +## Authority and admission + +Preflight returns the material document and its SHA256. The material binds the +catalog, immutable project snapshot, graph execution identity, definition, +source/input bytes, parameters, runtime closure, host/helper code, effective +permissions, environment and limits. Imported host code must match its current +files. Dispatch rechecks the approved host identity; the helper checks captured +and runtime files before READY and again before GO. + +An owner approves a specific material digest for one consuming actor for +60–3,600 seconds. The grant is nonsecret. An agent needs live `inspect` and +`execute` scopes plus that explicit grant. Existing classification, generation +and inference paths retain their owner-only execution rules. An owner can create +and consume a grant atomically, but must still submit the exact previously +reviewed digest. Code or input drift cannot silently refresh approval. + +Grant consumption, the Run, its bounded continuation and audit are one +PostgreSQL transaction. Grants are one-use; cancellation never refunds them. +Expiry/revocation are checked at consumption. Later cancellation controls already +admitted work. Revoking an approving credential does not retroactively revoke a +durable grant; explicit grant revocation does. + +An identical actor/request key/request reconciles the existing attempt even if +the grant later expires. A different actor or request conflicts. A lost commit +acknowledgement preserves captured files and does not make the attempt eligible +for the running queue. Explicit receipt reconciliation may make that same +committed attempt eligible. Restart never automatically replays work. External +retry means a fresh preflight, key and approval, not reuse of the old grant. + +## Process custody and recovery + +The sole Runs queue starts one pinned single-threaded Linux subreaper helper. +A private bounded socket protocol carries READY, GO, cancellation and custody +receipts; recipe stdout cannot declare completion. The helper and executable +bytes use sealed descriptors. Recipe code receives its own stdin/stdout/stderr, +not the helper's control descriptors. + +The helper establishes custody before READY and cannot create recipe children +until GO. Runs commits the exact helper identity and conservative `go_intent` +before sending GO once. Unknown acknowledgement means no GO. A restarted server +never resends it. Controller EOF requests cancellation and drainage. + +Cancellation repeatedly identifies direct/adopted children, signals verified +pidfds, reaps them and repeats as descendants become adopted. Detached sessions, +double forks and ignored TERM do not establish escape from this lifecycle. +Only the exclusive helper's `ECHILD`, after spawning closes and streams drain, +proves cessation. Empty process scans and dead leaders do not. Wall time, +bounded diagnostic streams, per-process file limits and output observation are +not aggregate resource or adversarial containment guarantees. + +Readiness is bounded at 10 seconds, TERM grace at 3 seconds and cleanup at +10 seconds. The controller independently bounds observation even if the helper +stops running. A missing or invalid drainage receipt after GO intent produces +`unknown` and fences further external execution for that host boot. Merely +acknowledging the error cannot clear the fence. A later valid receipt or a changed +boot ID can prove cessation, never reconstruct successful completion. Legacy +closed CPU-worker recovery remains separate. + +## Results and retained evidence + +After verified drainage and successful exit, Runs independently checks the +approved output names, roles, required files, sizes and hashes; symlinks, special +files, undeclared names and output drift fail. Captured regular files and custody +and artifact receipts are fsynced before the completed PostgreSQL transition. +A failed/cancelled/unknown attempt exposes no successful result. Ambiguous +publication acknowledgements preserve evidence for reopening. + +Every result read checks the retained material/spec, custody receipt and artifact +inventory against the approved contract, then verifies bytes. A changed result +is unavailable rather than silently trusted. Neutral lifecycle tests and native +READY/STOP are labelled as such; neither represents scientific/model acceptance. + +## HTTP projection + +All routes require the same catalog actor used by domain calls. + +- `POST /api/workspace/graphs/external`: name, project and recipe references, + expected recipe hash, exact named inputs and optional typed parameters. +- `GET /api/workspace/projects/{id}/recipes/{ref}?expected_sha256=...`: declarative + preview only. +- `POST /api/workspace/graphs/{id}/preflight-external`: `{revision}`. +- `POST /api/workspace/runs/approve-external`: graph ID/revision, expected digest, + consuming actor ID and optional TTL. +- `POST /api/workspace/runs/submit-external`: request key, graph ID/revision, + expected digest and optional explicit approval ID. +- `POST /api/access/execution-grants/{id}/revoke`: empty object, owner-only. + +Existing Run list/get/cancel/artifact routes serve these attempts. Classification +predictions and test-exposure operations do not apply. Schema 8 adds local grants +and immutable consumption records; explicit quiesced upgrade and versioned +backup/restore retain schemas 1–7. diff --git a/docs/contracts/workspace-storage.md b/docs/contracts/workspace-storage.md index 227f8135..a8f069d7 100644 --- a/docs/contracts/workspace-storage.md +++ b/docs/contracts/workspace-storage.md @@ -49,8 +49,8 @@ upgrade. ## Upgrade an existing catalog -Fresh catalogs use schema 7. Ordinary application startup **does not migrate** -an existing schema-1 through schema-6 catalog. It refuses with instructions to run the +Fresh catalogs use schema 8. Ordinary application startup **does not migrate** +an existing schema-1 through schema-7 catalog. It refuses with instructions to run the explicit upgrade. Stop every application, provider/training worker and artifact writer; keep them stopped throughout backup, upgrade and verification. The catalog advisory lock coordinates cooperating commands, but cannot fence an old binary @@ -66,7 +66,7 @@ python app.py --data ./dataset The backup destination must be new. Keep the complete backup and its receipt. The accepted transitions have stable identities `workspace-metadata-1-to-2`, -`audio-metadata-2-to-3`, `spatial-metadata-3-to-4`, `project-metadata-4-to-5`, `field-sequence-metadata-5-to-6` and `access-metadata-6-to-7`. The command applies the ordered steps needed by the +`audio-metadata-2-to-3`, `spatial-metadata-3-to-4`, `project-metadata-4-to-5`, `field-sequence-metadata-5-to-6`, `access-metadata-6-to-7` and `execution-approvals-7-to-8`. The command applies the ordered steps needed by the recognized source, with the complete chain in one transaction. It verifies: 1. The manifest, catalog identity, version ledger and exact retained definition. @@ -83,26 +83,26 @@ recognized source, with the complete chain in one transaction. It verifies: All DDL and version ledger updates commit in one transaction under the existing dataset advisory lock. A failed second step rolls back the first step as well; the old kind constraint is never authoritatively absent. Only the known version-1, -version-2, version-3, version-4, version-5 or version-6 definitions are eligible. Unknown versions, altered constraints, +version-2, version-3, version-4, version-5, version-6 or version-7 definitions are eligible. Unknown versions, altered constraints, indexes, tables or triggers, malformed ledgers, missing catalogs and contradictory identities fail closed. No command refreshes a signature to bless unsupported drift. The manifest remains version 1; manifest and SQL schema versions are different contracts. The command prints the dataset identity, final migration name -(`access-metadata-6-to-7`), final schema version, definition/structure hashes and +(`execution-approvals-7-to-8`), final schema version, definition/structure hashes and `upgraded` or `already_current`. A repeat on a -known schema-7 catalog verifies its structure and leaves rows/files unchanged. +known schema-8 catalog verifies its structure and leaves rows/files unchanged. Run one upgrade/transfer command at a time. A command failure rolls back its transaction. A lost commit acknowledgement is explicitly an unknown outcome: keep writers stopped, reopen, and rerun this same command to verify whether the -catalog is still the known source version or already known schema 7. Never +catalog is still the known source version or already known schema 8. Never manually change the ledger, delete a table or replay a training request to resolve it. ## Backup, restore and legacy imports The backup container remains `format_version: 1` and explicitly records -`schema_version: 1`, `2`, `3`, `4`, `5`, `6` or `7`. `backup_metadata.py` accepts each recognized schema. +`schema_version: 1`, `2`, `3`, `4`, `5`, `6`, `7` or `8`. `backup_metadata.py` accepts each recognized schema. Restore recreates **the exact backed-up schema version**, identity, rows, sequence states and ordinary files in an absent catalog/new directory. A retained schema-1, schema-2 or schema-3 backup remains restorable; upgrade that restored copy explicitly @@ -115,11 +115,11 @@ specified in [local storage and recovery](local-storage.md). `Metadata(..., schema_version=1)`, `schema_version=2`, `schema_version=3` and `schema_version=None` are tooling entry points for exact old-version restoration and recognized-version inspection. -Normal Dataset and Workbench callers omit that argument and require schema 7. +Normal Dataset and Workbench callers omit that argument and require schema 8. Version selection never authorizes an unsupported definition or structural drift. Legacy SQLite preflight still recognizes only the original 19 owner tables. -A new import creates schema 7 and leaves workspace/project tables empty. +A new import creates schema 8 and leaves workspace/project tables empty. A retained schema-1 or schema-2 migration receipt remains byte-for-byte authoritative: an interrupted import continues at its receipt's version, and a completed import can be reconciled after an explicit upgrade only while its original rows/files still @@ -128,7 +128,7 @@ never rewritten to imply that later workspace or audio writes belonged to the ol There is no automatic downgrade. Before any new writes, retain and restore the complete pre-upgrade backup to a separate destination/database if returning to -the older binary is necessary. After new writes, retain the schema-7 catalog and +the older binary is necessary. After new writes, retain the schema-8 catalog and artifacts and reconcile/export them under an explicit recovery decision; an old backup cannot represent those later writes. @@ -211,3 +211,21 @@ valid until their original expiry; protect backups like the original catalog. Old schema-6 backups restore exactly as schema 6 and require explicit upgrade. The application owns append-only audit/admission behavior; direct database access remains local administrative authority. See [actors](actors.md). + +## Material execution approvals (schema 8) + +The exact schema-7 definition is retained as `TABLES_V7`, hash +`d627be1cb07034e4c436e77e76eca19462dcd76f8c61520705d43d7542f7d624`. +The explicit quiesced transition `execution-approvals-7-to-8` adds +`access_execution_grants` and `access_execution_consumptions`. Grants bind +catalog, approving actor/credential, consuming actor, material SHA256, creation +and expiration epochs, and optional revocation epoch. Consumption uses the +grant ID as primary key and unique Run/admission IDs, retaining consuming +credential, request SHA256 and consumption epoch. No existing table changes. + +Access serializes consumption/revocation on the grant row. Runs owns the +transaction containing consumption, closed admission, Run and audit. Metadata +does not interpret executable recipes or synthesize approval. Integer/text +columns use the existing backup format; retained schema-7 backups restore +exactly and must be explicitly upgraded. Complete schema-8 backups preserve +approval state and identities; recovery does not implicitly refund approvals. diff --git a/docs/plans/generic-scientific-projects/execution-ledger.md b/docs/plans/generic-scientific-projects/execution-ledger.md index 348aad83..c99105a5 100644 --- a/docs/plans/generic-scientific-projects/execution-ledger.md +++ b/docs/plans/generic-scientific-projects/execution-ledger.md @@ -73,3 +73,15 @@ is the acceptance gate before P3b implementation. No merge/deployment. An environment disconnect notice did not remove the workspace or stop tool access. Verified branch and pending sources at2476a7d before publication; work continued. + +## 2026-10-13 — P3a hosted qualification and P3b admission + +PR47 exact d3c0e09908643b1b05a307a4c573df1458b97b29 passed UI38433532851 and all129 lifecycle38433532949 steps. Workspace clean; no merge. Created feature/approved-external-recipes-20261013. Independent P3b design review accepted one existing queue, exact material approval, captured recipe bytes and a pinned subreaper helper with READY/GO barrier. Missing drainage after GO intent remains unknown and fences external work for the same boot. See [P3b admission](reports/p3b-admission.md) for API, effective authority, runtime assumptions and disjoint write inventory. + +## 2026-10-13 — P3b implementation and local qualification + +Implemented external graph/preflight, exact actor-bound approvals/schema8, captured runtime/source/input identity, and process custody through the existing Runs queue. Root owns Runs/API/publication, volume_assets Access/schema, milestone_audit host/Projects/Pipeline, recipe_design helper/native probe, mesh_ui UI, point_assets composed integration tests; mesh_review independently reviewed backend and UI. + +Full stable-source suite749 passes856.353s with2 optional-reader skips separately covered20 tests; all176 Python sources/tests unchanged. Focused approvals/storage50, host/retained28, helper11 and composed external15 pass. Existing31 JS checks and new external controller pass. Actual owner/agent desktop/narrow browser, cancellation/restart and exact downloads pass; project/recovery regressions pass. Native237-byte READY/STOP reaches exit0/ECHILD only, no simulation/model claim. Independent review findings fixed with regressions; no remaining local blocker. See [P3b verification](reports/p3b-verification.md). + +A further disconnect notice did not block tools or remove work; branch and test progress were checked directly. Fresh main remainsc522bf6; PR32/33 and38–47 preserved, all unmerged. Commit/push/draft publication follows; exact-head hosted lifecycle/UI qualify P4 admission. No merge or deployment. diff --git a/docs/plans/generic-scientific-projects/plan.md b/docs/plans/generic-scientific-projects/plan.md index 70370c8b..79212004 100644 --- a/docs/plans/generic-scientific-projects/plan.md +++ b/docs/plans/generic-scientific-projects/plan.md @@ -2,9 +2,9 @@ **Plan status:** `Active` -**Current phase:** P2 qualified at published commit2476a7d; P3a scoped local actors admitted on feature/scoped-local-actors-20261013. +**Current phase:** P3a qualified at published commit d3c0e09; P3b approved external recipes admitted on feature/approved-external-recipes-20261013. -**Next slice:** P3a — shared actor authority and explicit current-client migration; P3b external process custody follows after this checkpoint. +**Next slice:** P3b — exact material approval, captured external recipes and descendant custody; see the P3b admission report for the reviewed contract and write set. **Acceptance status:** `partial` @@ -200,7 +200,7 @@ Statuses below track the approved staged implementation. Before starting each mi **Acceptance gate:** G5 shared service portion and G6. Use a real bounded executable for lifecycle tests, clearly labelled non-scientific; actual native lab probe decides admission of P4. No false success after cancellation or partial outputs; stale authorization and forged review denied across direct HTTP and UI. -**Status:** `Planned` +**Status:** `Verifying` ### P4: Optional Rheon generation controls diff --git a/docs/plans/generic-scientific-projects/reports/p3b-admission.md b/docs/plans/generic-scientific-projects/reports/p3b-admission.md new file mode 100644 index 00000000..db0e6914 --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b-admission.md @@ -0,0 +1,46 @@ +# P3b admission and write boundaries + +Prerequisite satisfied: PR47 exact d3c0e09908643b1b05a307a4c573df1458b97b29 passed hosted lifecycle 38433532949 (129 steps) and UI 38433532851. The existing P3a milestone remains owner-only for all current execution. Do not relax those paths merely to introduce approved external submission. + +Decision: adopt the conservative same-boot external-execution fence. After durable GO intent, a missing/dead helper without a verified drain receipt is unknown even if its PID ceased. A boot-ID change can prove prior processes ceased; a human acknowledgement cannot. This is an explicit honest platform limitation, not a new permission question or a sandbox claim. + +One existing Runs queue supervises one private single-threaded subreaper helper per external attempt. No second scheduler. The helper is pinned Tuldok code, establishes subreaper before recipe creation, closes unrelated descriptors, declares READY on a separate custodian channel, and waits on an explicit private GO barrier. Recipe output never shares the authority of custodian receipts. Persist helper identity and GO intent before sending GO; no GO on unknown commit acknowledgement. Reopening never resends GO. Parent pipe loss cancels and drains the helper's descendants. + +Drain by pidfds and repeated adopted-child PPID scans/reaping to ECHILD, including setsid/double-fork descendants. Stop all recipe spawning before accepting ECHILD. Incomplete scans, identity/OS failures, unconfirmed descendants or elapsed cleanup budget yield unknown and retained evidence. No leader-only or empty-scan cessation inference. Resource declarations distinguish wall/output limits and inherited per-process RLIMITs from unsupported aggregate/security guarantees. + +Use an explicitly selected generic project recipe definition, with a finite source closure, configured runtime identity, bounded argument vector (no shell), typed parameters, exact input references/hashes, declared output roles, environment allowlist, resource limits and honest filesystem/network assumptions. Opening or validating never imports project code or discovers executable hooks. Capture approved source bytes under private staging; execute only captured source and a verified trusted runtime installation/captured executable handle. Never certify a mutable pathname by a pre-launch hash alone. + +Material approval binds catalog/project snapshot, graph execution digest and recipe version, captured source and runtime closure, exact input hashes, parameter values/seed, permissions/environment/resources, allowed consuming actor and expiry. Owner-only approve-execution creates a one-use grant. Atomic submission consumes it with the Run and admission/audit. Same actor/key/digest reconciles the existing attempt; changed actor or digest conflicts. Retry requires a fresh approval. Owner execution can create and consume its own exact approval in the same transaction; agents cannot mint approval. Cancellation retains P3a's explicit catalog scope. + +First checkpoint is a bounded neutral real executable: read an admitted input, spawn a bounded descendant, write structured progress plus an output manifest, and survive ordinary completion/cancel/restart qualification. UI uses existing Pipeline/Run owners with compact recipe/parameter controls and a concise material approval summary. No claim of scientific acceptance. A real native ready/stop child must also run behind the production helper before P4. + +Publish only after durable helper drain receipt and independently verified bounded regular outputs. Stage filesystem and PostgreSQL ordering reuse existing immutable publication/unknown-commit semantics. Keep old CPU/integrity run envelopes, recovery rules, artifact bounds and frozen bytes unchanged; external recipes select separate custody rules within the same Runs owner. + +Write boundaries for review: Access/schema upgrade/approval tests; recipe_process.py standalone custodian and real lifecycle fault tests; generic recipe-definition capture and Projects/Pipeline integration; Runs dispatcher/recovery/publication; existing UI controllers and auth-aware browser checkpoint; contracts, plan and evidence. Assign disjoint ownership only after exact API/design review. No external producer-specific branch in core. + +P5 follow-on decisions remain separate: trajectory CPU script permits fresh CPU provenance without altering historical freeze, but installed2.8CPU is not managedPumas2.14/CUDA acceptance; parallel Rust target needs missing locked crates; full120-frame fields exceed existing40MiB/64MiB bounds. Keep old bounds and plan ordered16-frame lossless generic chunks with shared trajectory families plus bounded original artifacts. No decimation or fabricated frozen-input node. Disk currently13GiB free, so measured/reserved full output + staging/backup budgets must be checked before admission. + +Independent review refinement: owner submit must carry the exact previously reviewed material preflight digest/token; atomic approval creation/consumption may not silently approve newly recomputed source/runtime/parameter drift. Agent grants bind the same digest and actor. Dispatch revalidates captured inputs/runtime and fails closed on mismatch without refreshing approval. Grant expiry/revocation apply at consumption; post-admission stopping uses cancellation, with no refund/reuse. A row/audit transition marked completed must bind the helper drainage and verified artifact receipts. + +## Reviewed owner contracts + +One queue remains in Runs. Pipeline owns an external graph variant and `preflight_external(graph_id, revision)` without a persisted preflight registry. Runs owns approve/submit against the reviewed material digest and existing status/cancel/artifact surfaces. Access owns grant/revoke and an existing-transaction consume primitive; existing execute guards stay owner-only. The first graph is explicit project inputs → one executable recipe → declared outputs, not an unused frozen release or general DAG executor. + +The helper owns a private bounded control channel, READY/GO barrier and drainage receipt. Runs persists GO intent before sending GO; recovery never resends. A separate recipe contract/capture module owns declarative validation, material identity and output checks, with no scheduler. Initial runtime profiles are explicitly configured trusted system installations under resolved `/usr`, owned by the explicitly qualified installation UID (0 on ordinary hosts; 65534 in this container), distinct from the application UID, and non-group/world-writable; pinned closure hashes and installation assumptions are recorded. Workspace model environments remain unqualified until separately admitted. Effective same-UID filesystem/network authority is disclosed; environment cleanup and approval do not create confinement. + +## Exact write inventory and standards routing + +- Access/schema owner: `access.py`, `metadata.py`, `upgrade_metadata.py`, `tests/test_access.py`, `tests/test_spatial_storage.py`, new `tests/test_execution_approvals.py`, `docs/contracts/actors.md`. Preserve exact schema7 definitions and versioned backups. +- Helper owner: new `recipe_process.py`, `tests/test_recipe_process.py`, `tests/fixtures/external_recipe.py`; corresponding helper section in `docs/contracts/external-recipes.md`. +- Contract/graph owner: new `recipe_contract.py`, `tests/test_recipe_contract.py`; `projects.py`, `pipeline.py`, `tests/test_projects.py`, `tests/test_pipeline.py`. +- Root integration: `runs.py`, `app.py`, new `tests/test_external_runs.py`, `tests/test_external_http.py`; existing `tests/test_runs.py`, `tests/auth_helpers.py` only for explicit new admission fixtures. +- UI owner: `static/workspace-real.js`, `static/workspace-service.js`, `static/workspace-projects.js`, `static/workspaces.js`, `static/workspaces.html`, `static/workspaces.css`, new `static/workspace-external.js`, `tests/browser_workspace_external.cjs`, relevant workspace controller tests. +- Evidence/packaging: `README.md`, `.github/workflows/tests.yml`, `docs/contracts/external-recipes.md`, this plan directory and dedicated browser screenshots/receipts. Any additional path requires documented scope update before edit. + +Apply adopted architecture/ownership, Python, JavaScript, security/untrusted-execution, persistence/transaction, dependency and testing standards. Independent design review accepted minimal six-owner composition; no second queue, generic job framework or persistent preflight authority. Verification must exercise material drift, grant races/reuse/revocation, lost acknowledgements, READY/GO crash boundaries, descendants/output flood, restart unknown fence, cold output corruption, historical Runs and compact UI parity. No Standards Engine certificate or model acceptance is inferred from these tests. + +Implementation clarification: the system Python closure also includes the exact read-only `/etc/python3.13/sitecustomize.py` target referenced by the installed stdlib, under the same trusted installation-owner policy. `-I -S` disables automatic site imports. The admitted write set includes `tests/test_workspace_metadata.py` and `docs/contracts/workspace-storage.md` for schema8 assertions and persistence documentation. No blanket `/etc` trust or workspace-venv qualification is inferred. + +Final review refinements: an in-memory confirmed-admission set gates external queue dispatch, so a committed row with a lost response cannot run until explicit same-request reconciliation. The controller independently bounds helper observation even when the helper is stopped. Helper-owned canonical spec encoding is used for Unicode identities. Capture fsyncs directory entries, and cold material/spec/output validation checks approved projections before path reads. UI pending submissions retain their actor and exact request after ambiguous responses, including subsequent permission denial; late responses cannot replace newer view/session intent. Tests for these findings are part of P3b acceptance. + +Portability correction: the initially observed `/etc/python3.13/sitecustomize.py` is one configured-version instance. The allowed target is now derived from the verified `/usr/bin/python3.N` name, preserving an exact path for each installation. No arbitrary configuration directory or runtime path is admitted. diff --git a/docs/plans/generic-scientific-projects/reports/p3b-native-probe-receipt.json b/docs/plans/generic-scientific-projects/reports/p3b-native-probe-receipt.json new file mode 100644 index 00000000..b685647d --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b-native-probe-receipt.json @@ -0,0 +1,82 @@ +{ + "qualification": "native_ready_stop_only", + "executable_sha256": "4e4e49f0e3febf5b11556c2a1daac3dc684e9fb9a9c3c742329d804a4913ceff", + "helper_sha256": "f73d0881c9c3d509616e11e783a65e2bce2b9eeb9afa467602b953c93d0298f5", + "runtime_closure_sha256": "418e458318bf71ed2739e98aab4778cfa9c91171b5982f803734823c6d1159dc", + "runtime_file_count": 1316, + "trusted_install_owner_uid": 65534, + "stdin_hex": "00", + "stdout_bytes": 237, + "ready": { + "actual_divergence_limit": 1e-05, + "density": 1.25, + "dt": 0.016666666666666666, + "face_lengths": [ + 576, + 576, + 576 + ], + "method": "jacobi", + "n": 8, + "native_relative_residual": 1e-08, + "schema": "rheon-trajectory-v1", + "seed": 100, + "spacing": [ + 0.125, + 0.125, + 0.125 + ] + }, + "receipt": { + "attempt_id": "0f6af4bf1aeb41c2a784951653ac589e", + "drained": true, + "echild": true, + "go_received": true, + "helper": { + "boot_id": "14f8821d-b20e-4ebd-87a4-df441b737def", + "pid": 278976, + "start_ticks": "2845761" + }, + "leader_returncode": 0, + "outcome": "completed", + "reason": "exited", + "request_sha256": "58e06d2e8604624cbc7a49f044781de2dba50ac3c2f0cb5d14c339d9e4b8b1a5", + "schema_version": 1, + "spawn_closed": true, + "spec_sha256": "76774eb4b3a87461fe6c83e6f28b9b52ec8fbb35baf169b08e64ac63d3e71657", + "streams": { + "stderr": { + "bytes": 0, + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + "stdout": { + "bytes": 237, + "sha256": "1daa93f8bbd5bb5bd48ac394053139c64804d1eb7db51c2f23a7f4a5ef0f87f5" + } + } + }, + "limitations": [ + "No frames generated; no numerical or model acceptance.", + "Native direct dependency closure is included in the trusted system runtime inventory; this is local ready/stop qualification, not hosted or GPU qualification." + ], + "runtime_bytes": 64246348, + "full_evidence_sha256": "e88d1bd1e4a89c48a9b2eaa90ab82149cb45a67a1747667a21f91b7af29d44a3", + "native_dependencies": { + "/usr/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2": { + "bytes": 225672, + "sha256": "438c546d8e8cc48496bf3a95f753051afd9db66a629a74e31a9ded71586b56e0" + }, + "/usr/lib/x86_64-linux-gnu/libc.so.6": { + "bytes": 1995216, + "sha256": "fa430b8f298f817a266046af84a77533185ad6fc4406c7d3787b5a0a0c207826" + }, + "/usr/lib/x86_64-linux-gnu/libm.so.6": { + "bytes": 977112, + "sha256": "6d567d53e895273ca14a1f9dc164fc6c8d39aed2f60aa46a733c2784228915f3" + }, + "/usr/lib/x86_64-linux-gnu/libgcc_s.so.1": { + "bytes": 182856, + "sha256": "30c61ab012a4241bed033725a09b61f5fdd3bb7df95ee852d0b096520524c7af" + } + } +} diff --git a/docs/plans/generic-scientific-projects/reports/p3b-native-probe.md b/docs/plans/generic-scientific-projects/reports/p3b-native-probe.md new file mode 100644 index 00000000..c851d33f --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b-native-probe.md @@ -0,0 +1,34 @@ +# P3b native ready/stop qualification — 2026-10-13 + +The production `recipe_process.py` helper completed a real native ready/stop +exchange with the pinned `rheon-trajectory-probe`. No native/lab source was changed, +no frame was requested, and no model was loaded or trained. + +- Source pins: lab `e8a90bfef6b2955c502008ccc62443e29dd9f2ec`; + Rheon `2209012bc5f902693d0f695ec1c2d854126af317`. Scratch build uses Rust 1.92.0. +- Native executable SHA256: `4e4e49f0e3febf5b11556c2a1daac3dc684e9fb9a9c3c742329d804a4913ceff`. +- Production helper SHA256: `f73d0881c9c3d509616e11e783a65e2bce2b9eeb9afa467602b953c93d0298f5`. +- Arguments: `8 jacobi 100`. Captured stdin: one byte `00` (stop). +- The helper established READY, received GO, executed the sealed native binary, + captured exactly 237 stdout bytes (one length-prefixed `rheon-trajectory-v1` + ready envelope), and observed leader return code 0 followed by ECHILD. +- Durable receipt: completed, spawn closed, drained, ECHILD true. Stderr empty. +- The declared system runtime plus recursively inspected native ELF dependencies + contained 1316 files / 64246348 bytes. All + dependency files resolved under `/usr`, with installation owner UID + 65534, no group/world write, and no current-user write; + the already admitted Python sitecustomize exception remains in the helper's + system inventory. The helper rehashed this captured inventory before READY and GO. +- Runtime closure SHA256: `418e458318bf71ed2739e98aab4778cfa9c91171b5982f803734823c6d1159dc`. + +Compact receipt and direct native library identities are retained in +[p3b-native-probe-receipt.json](p3b-native-probe-receipt.json). +The full measured inventory, control events, raw logs and receipt remain under +`/workspace/scratch/tuldok-p3b-production-native/`; `qualify.py` reproduces this +local probe into a fresh UUID directory using the existing pinned binary. + +This establishes local native process custody and wire readiness only. It does +not establish simulation accuracy, generated trajectories, training, GPU/Pumas +acceptance, hosted native runtime portability, or the later scientific milestones. +The direct native invocation is a helper qualification; the admitted application +recipe profile remains the reviewed system-Python profile. diff --git a/docs/plans/generic-scientific-projects/reports/p3b-verification.md b/docs/plans/generic-scientific-projects/reports/p3b-verification.md new file mode 100644 index 00000000..713438bf --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b-verification.md @@ -0,0 +1,87 @@ +# P3b verification + +Status: local integration and full regression verified; published exact-head CI remains pending. Independent final +backend and UI re-review found no remaining blockers. P4 implementation remains gated on P3b +hosted lifecycle and UI success. No merge or deployment. + +## Delivered behavior + +Explicit project recipe definitions now produce editable input → execute → output +graphs. Preflight binds source/input/runtime/host/parameter identities; owner +approval and scoped agent consumption are atomic with the existing Run admission. +Schema8 retains old schema/backup identities. The sole queue uses a pinned Linux +subreaper helper, durable GO intent and independent controller deadline. Missing +drainage after possible execution stays unknown and fences external work. +Declared output bytes and custody receipts survive restart and are checked on +read. The public runtime is the explicitly trusted system Python installation; +filesystem/network authority is disclosed, not described as isolated. + +## Completed evidence + +- Full stable-source Python suite at `c8ba1ad`: **749 tests pass in856.353s**, with two optional-reader skips independently covered by20 passing spatial reader tests. All176 Python runtime/test files remained unchanged (aggregate `0a01e023016dc17405966eeb900e90edeb1ceb84725309676f33d8381459792e`). + +- Access/schema/storage: 50 tests, including approval races, rollback, committed + but unacknowledged consumption, exact schema7 and schema8 restore. +- Host/Projects/Pipeline: 28 tests; final five host tests rerun after cold material + validation, with spec/material tampering and no-execution checks. +- Helper: 11 real lifecycle/fault tests, including READY/GO, controller loss, + setsid/double-fork descendants, ignored TERM, bounded output, helper death, + receipt failure, repeated cancellation and late BrokenPipe. +- Composed Runs/HTTP: final15 tests pass in56.182s. They exercise owner grants, + wrong actors, revoked grants, drift, transaction rollback, active-queue lost + acknowledgement fencing, GO-commit loss without execution, Unicode arguments, + real cancellation, exact output/download/restart, altered artifacts and actual + SIGSTOP helper deadline followed by independently verified cleanup. +- Actual native helper checkpoint: 237-byte Rheon READY response, STOP, exit0, + `ECHILD` and durable drainage. See [native report](p3b-native-probe.md) and + [receipt](p3b-native-probe-receipt.json). Zero simulation frames generated. +- Browser: keyboard graph creation/edit, exact review, stale-byte refusal before + admission, actual descendant work, exact output bytes, separately authenticated + agent using an owner grant, cloned cancellation and restart. Desktop1440 and + narrow390 captures are retained in [p3b](p3b/receipt.json). +- Independent spatial readers:20 tests pass without skips. +- Existing project and recovery browser regressions pass. Thirty-one existing JS + checks pass, with the browser-backed rights artifact check rerun in the proper + PostgreSQL/Chromium environment after an initial missing-environment timeout. + The new external controller test covers uncertain request custody and late + response/session fences. +- Adopted standards plan-contract validation, Python/JS syntax and whitespace + checks pass. No static type-checker or Standards Engine certificate is claimed. + +## Independent review and corrections + +Separate owners reviewed Access/admission, host capture, process lifecycle and UI. +Review fixed double staging creation, exact approved-spec projection, imported +helper identity, retained output bounds, directory durability, unknown-commit +queue eligibility, Unicode spec canonicalization, an independent parent deadline +and cancellation-channel closure. UI review preserved an actor-bound unresolved +key after permission failure and fenced asynchronous adoption/navigation. + +The initial focused13 integration run passed12 and exposed one test fixture that +needed complete custody identity. The following14 run found a real late-cancel +channel race, fixed in the helper and covered by deterministic and repeated real +cancel tests. Final15 passes above supersede those failures. Mocks only inject +specific faults; neutral completion and drainage use actual processes. + +## Boundaries + +No scientific/model/GPU acceptance is claimed. P4 generation, P5 fitting and +rollout evaluation, P6 agent transport and P7 full scientific workflow remain +open. ASR and general 3D training remain outside this concrete recipe acceptance. +A killed custodian can leave descendants alive; the observed same-boot unknown +fence is deliberate and cannot be dismissed with an acknowledgement. This is +trusted-code lifecycle custody, not hostile-code confinement or aggregate +resource enforcement. + +## Runtime path portability follow-up + +Post-publication inspection found that the system Python configuration exception +was hard-coded to3.13. Both live and cold checks now derive the exact allowed +`/etc/python3.N/sitecustomize.py` from the already validated interpreter name; no +broader `/etc` access is accepted. Six focused host tests (including cold3.12/3.13 +matching and wrong-version refusal), four real HTTP tests and the complete real +external browser pass after this change. These cold fixtures are not a claim of +executing Python3.12 locally. Root independently reviewed the two-line runtime +change. Hosted final-head CI reruns full regression; the176-file inventory records +the earlier full suite, while source-files.json and browser receipts pin the +follow-up sources. diff --git a/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-1440.jpg b/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-1440.jpg new file mode 100644 index 00000000..70bbbb22 Binary files /dev/null and b/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-1440.jpg differ diff --git a/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-390.jpg b/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-390.jpg new file mode 100644 index 00000000..312e290f Binary files /dev/null and b/docs/plans/generic-scientific-projects/reports/p3b/external-pipeline-390.jpg differ diff --git a/docs/plans/generic-scientific-projects/reports/p3b/external-runs-1440.jpg b/docs/plans/generic-scientific-projects/reports/p3b/external-runs-1440.jpg new file mode 100644 index 00000000..80b663d2 Binary files /dev/null and b/docs/plans/generic-scientific-projects/reports/p3b/external-runs-1440.jpg differ diff --git a/docs/plans/generic-scientific-projects/reports/p3b/external-runs-390.jpg b/docs/plans/generic-scientific-projects/reports/p3b/external-runs-390.jpg new file mode 100644 index 00000000..04e5cad2 Binary files /dev/null and b/docs/plans/generic-scientific-projects/reports/p3b/external-runs-390.jpg differ diff --git a/docs/plans/generic-scientific-projects/reports/p3b/python-source-files.json b/docs/plans/generic-scientific-projects/reports/p3b/python-source-files.json new file mode 100644 index 00000000..49074bf1 --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b/python-source-files.json @@ -0,0 +1 @@ +{"access.py": "cbf1d2016b43cc85747fefe12da041ebb74004395b833492340fa7ae036183e4", "ai.py": "a3b04a3015496ff3c66c3eb450ccf887bd5726229669ac0515d95a2761ad3a9a", "ai_codex.py": "debd26342e73a87635d772e3ee59d30bb822877008d667b47997f52e22f94f16", "ai_http.py": "73ca648fe00e8f5a4022b14b72c80dd695228706a0f2b79aee605a524b8f2585", "ai_openrouter.py": "70930124fac7ef08941f571c1d4492f72b29aa94807cfd5d66bc32555432b160", "app.py": "589c2185cbbc512cc2907fd086f38a91749d3665afa61e29a0707242069d2810", "audio_assets.py": "d69bfa94037ea132be4adebba26c4389d58925a408f2fc27c6984a71fc8dc1cd", "audio_classification_export.py": "0f0643470cfa3b015c2d56c0e8e1dc2ad4944bc825127b9131fbbdd36349052d", "audio_export.py": "bc20d32089b3a004504c6cb072e18db9e285c9195db84679670fe460ef51cfc9", "audio_training.py": "fd5a21f1bfbfbbd72f8ba5a3bcc88017e2b8c2f075a7a6506310a01156f771a7", "backup_metadata.py": "15fced02dbc6da6b035b2ab7fbf5bd368ef862d0d03eb01561781d09fb921f0a", "bulk_import.py": "d09fe5973d4cd405b99423989a29de91fee710c56523f48f77a1c4e6fb03ed39", "canonical_release.py": "1f92e2d822602211475a5e7c13198388cc0a36aa36e0872f66d9fd353dcc2061", "caption_import.py": "e6e16f3a4977f03491d119bd8ef67430526e4fb100a2a4161d600df2d6eb8acc", "caption_proposals.py": "a74ca7993b6f3b7dc7fb867a871148f04c743c048a1e988ab517554a35ae901c", "curation.py": "b25576749afd01f9e699133c5db7e6113f9a5f0ad8961dafc4084292896b0049", "dataset_recipes.py": "78ae918228f15f9d5924985075cb96535b8953b4ad5faa821d0cacd0a50e3c88", "dataset_releases.py": "97b2045fcfda2adfaedd98cb8d42ccd72f093bab4d12bb902b940ae8a060f5e0", "frozen_classification.py": "a6a9fc244bcb7de7da5217fb36d5e73bb03ca1756c9c63770c23a78336606649", "gateway_discovery.py": "8a02e2ef9038859c1accce9ea3e31ea489423f19799a279f4be6f9afd61297d0", "grounded_candidates.py": "55bf111d7dfe951fea960f347ed4bfb498d15dcc604bf46fb1ae2505cc1354cc", "image_classification_export.py": "995edefa24fc039505337fd8d2915e45d173c18a03af513d9f5d8eb234225b96", "image_generation.py": "c3a62b3cf0bf1d6f6d453a63f7f2a7d08de63864d880959bd0eab237d9856858", "image_training.py": "5a7807f8834f96bf17e1c020357fdb96a7eb1ac94b54a440db80559d9923f99c", "immutable_assets.py": "672c08d949f964fcd8cebd9a888092ab0163f022542df337e02bcb17f3c477c8", "mesh_release.py": "09d29a60bc37826b906097debaf7eb8577a425d3d791ff5df8d3b03607b10de1", "meshes.py": "abeca65f8a39af57352828169f90f767b6bc770fb5407fb3f18af53be8ff84e2", "metadata.py": "42559a7efd599f637e6e289802fa7400d59b2915edcf64e3260952d59cd7b439", "migrate_sqlite.py": "be1a79a1b6f5e2c8e4c99862043a5afcd4f30d6539388c1600908f4a4f3f92da", "native_detection_import.py": "80466232bd51f58bca9a00ef68e278da087b012e7f1b3b1171e6e51db3b8c572", "native_text_import.py": "8e1d53558dca265812792a9ec0802994cf200fd448b6dd11560667d07f64af2c", "pipeline.py": "030b08b215b37701ec2b9a4f00240edef05213191b9568abdb2f2f013ae84659", "pointclouds.py": "02d9eef31661dd5a9f0855f8e59d7b839b0ad1590f53a657123a5d9da789dd9a", "preferences.py": "d6279b18375fa8695584a02cfe962b56e77cf4f3521c5e33cc4baf09f8e4dab7", "projects.py": "d147c6bae61068f5517fd15e3512311459cd4de3d6edfdd9ea984783470d432d", "pumas_gateway_descriptor.py": "b9c4259bda856fd19d1d82b3a2c000a74ab3979832248fd3f1f1d3d6309c0752", "pumas_operations.py": "e8b8acee54a027633ae39f00a23b3d4845ae474d031690134cafb1c75bf73511", "pumas_vision.py": "5659c7731b5011ff39a0a9b7c27712382983f16286540f47f6b1337941bbda7d", "recipe_contract.py": "99b690dc56c4e73638e5a567f8c5f28b5c1f14d96aaee7679713a0d666196206", "recipe_process.py": "f73d0881c9c3d509616e11e783a65e2bce2b9eeb9afa467602b953c93d0298f5", "release_validation.py": "a04e0f3c941256422b0c3a8c28665b6fba025df9d3cfa6cd5d5686e2bb8de95b", "rheon_controls_contract.py": "25ec0f98f9b0ec576f30793cd24c1dd7b4e77fa7a6bfc6ed323271f829f982f4", "rheon_controls_sequence_contract.py": "5c41f3a3c848940191d05d9b5b01a2a398b0d2a67f23c603ab8e918897bd3b55", "rheon_sequence_contract.py": "063d17a3bbc92a27c26c0f5dd4588a9478091ebbf53ce0ccb818cee6a9393b98", "rheon_sequences.py": "9e3013fb1b5f1baf3de73678a26f964bc2f802435e6fff26476f816847fd22a5", "runs.py": "3237db72da8461fa6154955382a95290c1834448812ca00b0443d9c8025dfc3a", "saved_searches.py": "fcd4021fc20702568f1e44a165473aa752b9a9794a958ff31b33c42aba7114d5", "saved_selections.py": "4e89ee272fc8a685ec76b3737879d6560661a73e03fca264c2057785905418a3", "scientific_fields.py": "65d46550668e97cf51925298f18c4a9d0f0fe73d4a47389775ade457487cd608", "scientific_release.py": "2c6498521028da4501e1462ea6f418e87351a71fffd6ffaa010f07d86c8c3afc", "sequence_assets.py": "3ac8361f5e24f6b2af93dbd9030bab864da7bddb32da975d937e852d89fff98d", "sequence_batch_import.py": "3e7af45744ae7f8393059715dbf7012567d0bbb528c3682dd1b992141ae32b10", "sequence_release.py": "3d1bac3c2d78d75e08337b0659e435fc81c32c7625d8244be4d41f2ecb9e831c", "spatial_assets.py": "fdd3715025426024a4c8fa1704645d98940cab7e6002846b9e72a54352fe6ef8", "spatial_release.py": "4d6ec06fceb72257a9d25da09ab24bcf13fc38f66ae50e8b39d5a5796f9b357c", "synthetic.py": "dc55737b0f55ff4ec8df56a3d6b4f4596f5067bfd75672ba6326453047cab5e9", "tests/auth_helpers.py": "27a40542686a8a56df04601d765b0d4bf815d65d327b49931696a0ed161b5a7e", "tests/browser_caption_proposals_server.py": "b131aa4b8732ccd465b5b6c8ae9afc89365e4ae70375fdc0fb239df5e6bb7b06", "tests/browser_curation_server.py": "812eb92ca91e0c14e6a02a753e1554e5c499b198d659c90036fd2ee7ebef80d5", "tests/browser_grounded_server.py": "afa77db2d8d4ce01e8257c5d3b5a35cd2dc78bf3199cc306b307341748b170ea", "tests/browser_image_classification_server.py": "f5f3c3512823298afd6ea110b74bd617ef814e6e0d29cd35cd728760cbc32c34", "tests/browser_images_server.py": "1375a6a1d9e2727949254de9286fe0da51b69cf5cc55709ef5a9430c7cd0eb55", "tests/browser_metadata_server.py": "7aa0e25bae8eb5bdd523ea1b568e5ac60d9420e3aa8acd97750f95053f07f053", "tests/browser_pumas_gateways_server.py": "c17a4b267ea2e1385185f94685eca893691a8f966f46b89c3084e7ba8e8bdc3d", "tests/browser_pumas_typed_server.py": "fc729ef0b1e4cc107dab0fe5fe8a4b2e09fbb97d32f4f282ce5960f7e9f7ea35", "tests/browser_server.py": "6c3d57a4e5b5fe75ab866fcf35dc5450a98ed0170d0fbcc03d10f40761dc8d89", "tests/browser_text_classification_proposals_server.py": "c21f65529ad95962d295153c0a1f7cb29f03937f1496efa02ea3add4a5f14203", "tests/check_image_classification_consumer.py": "b8894a0c903ede4217671d817ef4a1ccc081d1f6f8548d99d7c24d375a882697", "tests/check_instruction_consumer.py": "d2b38df86311be0011aced1046c0fd7a7e8f667dee9b1e783a1ff9a189aab5d7", "tests/check_preference_consumer.py": "9b33ca4300fe6eac6fea14a1b2d24a598a7b50a60dcc81f224a0c1b0296bbf1c", "tests/check_text_corpus_consumer.py": "00bca07ab03912f4e6208c22aba1842b3a0b98111d28bc443d3ea94e0bdd0a26", "tests/fake_ai.py": "2eece3243b9c1594b7ed0f0a0dd9f20a453838d2e6b73ad058e217f688631a72", "tests/fake_ai_codex.py": "31ec8bebf169703cae1db8936c84ae983e57ba7d7dfa937e57bad4e575e41b88", "tests/fake_caption_model.py": "61a34f2584ce3f3de64075478103422fd04e562649875de97f4e029dbceae7b1", "tests/fake_classification_model.py": "27cb688d1f1c6d55bc742f8265c7a634133c94d94d4758b691e2b45b03fb7ab5", "tests/fake_grounded.py": "1edf38662b953dfbb6b3ff0460320b820d7bd6b6bbc6c07157835f3aa5a4afb2", "tests/fake_images.py": "c4a532a749211c6e67a5f7444eee698c8ac51f28cb3f636ddfcc6a9f1f5e4816", "tests/fake_pumas_typed.py": "95d0a2e8bf652e6f5165a8c2a9a2a5c2e7378c7680cc3e8c615e431210ae07f1", "tests/fake_pumas_vision.py": "bcdb4abf3ff170f26f6798a306db77f8ec3c370843905ac816e17b8593d47ddc", "tests/fixtures/diffusion_check_image_data.py": "6a4394308a4cc69b4ca965aca7f8459d7711ac9d51ce70492562c6ec6d806f94", "tests/fixtures/external_recipe.py": "06815b425a7722e0aa64d0c8739263fc2db371027b382d0c3326691305e1879c", "tests/fixtures/image_classification_fixture.py": "1e547f650f20e157eb0b3914213b9bd3ad26d989dabffbc975616b0d8fce77b8", "tests/fixtures/pumas-typed-v1/harness/probe_gateway.py": "79a4e88223fc94517ac00e8bf1f3a3d005fe2f12c527dab436d6c6e916567f5f", "tests/fixtures/pumas-typed-v1/harness/serve.py": "f3a7debf3a0ab69537cfdf3e9e51222c6ea322cbd47750a20aeac3f2dfacde69", "tests/fixtures/rheon_controls_authored.py": "385e20e96d0d0216662477491365490dddf5e6d693ced1ef5ac3845b3a9a3d8a", "tests/fixtures/rheon_source_derived.py": "884fb395fccc7f9f4b0ce82675eba5aec2621887b4ac1d93b71f2ab0abc99d3a", "tests/fixtures/text_corpus_fixture.py": "6d1cbef5f8f725bd75e16e9190160002f273d80d9e95c654e78ceda35c9c7d0b", "tests/fixtures/tiny_transformer/model.py": "d304e951615f3bcb9cd5f4158b7348c5ecfd68731d8a5d62bd0d98e837dd1784", "tests/fixtures/tiny_transformer/train.py": "8d2b908007dabbbd609312f1a22a697b40534b6c5ab07e3d540fd5833295e47d", "tests/fixtures/tiny_transformer/use_model.py": "34b94d2be0a870fc470d27e61738e7ff193b586122b72724f7a33f2688099957", "tests/fixtures/train_image_classifier.py": "a198463590d41660c21ae45313b47c3a5baf38889eb9bc029e4c7fe8aa741ac1", "tests/fixtures/workspaces/audio/classification_fixture.py": "39af3d407b76cc64625e838d78f6e55208bd0f55f6f36ecba3167a7f1b786dd5", "tests/fixtures/workspaces/audio/make_fixture.py": "6189d6dff75ca84240f1df5a1442d4ab25e4339431c985de25085d7bf41a4e58", "tests/fixtures/workspaces/image_corpus.py": "16f829699fc2de257bc8acf672af1d143bf74fcfbff33f030664e2745d958429", "tests/postgres_helpers.py": "eb8398f68b17d8f84309941058872c2d80d73d09e63c2c8cb4af4d8ec59c22bf", "tests/qualify_scientific_fields.py": "8418dba5856172d891375935b0b51bb2ba518db9dbadf4a2ecd8dfee5c625540", "tests/qualify_spatial_retained_runs.py": "2c7fca75747ab4639c4d9415b6308c7a3a3a46c7a257b76f8d97cb01c32fb358", "tests/test_access.py": "d135a0556a53fc5d173b8d3b4561e9f5d28d47defee299dbca2aff2cab7356e3", "tests/test_access_http.py": "25071bf2647fc6d8d3aa6ed525d45f777c01b6a7831f9802958e26a2e57147a7", "tests/test_ai.py": "71a1a4b653671ec0c37ecab1a34a69e8e523193741eecfbe1b6298ac8e964aee", "tests/test_audio_assets.py": "6c63a22d4ba93d41ef0ef6251abb720e50b3c2d240d0fdcd5ae0848d1be8956a", "tests/test_audio_data.py": "77af876b31b42efc68849b45272b696bf65b8d7b3adf4a125723f14125370f62", "tests/test_audio_training.py": "1756d9bd3d80202d16fa48e07003e915111db470e7e557369cb0e779aff2f275", "tests/test_bulk_import.py": "6c085c2a11bcd52e3a39a1c74a2fc84088160f970c22a99dea9eeec4c27a2d4b", "tests/test_caption_exports.py": "170207224c2b2393b701058ff46f73f13f3c6be6d623e451e89f0c3b1e25c40f", "tests/test_caption_import.py": "83d46023931d671035959dbdc45b1117f4c82b0d4abb110c35cd28274bf28fbf", "tests/test_caption_proposals.py": "b199041df42538ab7bf15d15700a1639bef49104c33505fad3584db78dbd128e", "tests/test_combined_workbench.py": "a6ff63d3dc3bb0ee02d2d94f390f4eff052008e2ecb08929e5be2d65b0921404", "tests/test_curation.py": "d0d592e869fe6ce4dd923ad5e6df7ba0f4357d337a4584419fd1206c0c21f144", "tests/test_dataset.py": "0938fcc8819dd0aaf4b400e8a715027a8d184c4dbe3f5789cc701ad1177383e4", "tests/test_dataset_releases.py": "32ee71ced83f17717980c1eb4375611b2483dbef9937c3e9b43a80817168e550", "tests/test_execution_approvals.py": "8368601c1cdb90504533e7f88a515101e7362ac780380224fac8a925c936bb2b", "tests/test_export_runs.py": "926d86a6331f90f61f846ca421aee0e6ebab650667788fa0c4ec2195c659d401", "tests/test_external_http.py": "dff9afebade39bc530575f19defbe6064ac39b5406a9e461fca7f1af6cf6e72c", "tests/test_external_runs.py": "59931dd73ebe7531e793a6dbe5ac4f9f9d5a6c8d6eb2df83930611d7e99118a4", "tests/test_gateway_discovery.py": "f67eaab50db54e1abac9bfadb51b1bfc807f43c8286dd8ebc4e1126f8f84edc9", "tests/test_generation_job_api.py": "bcb9c18eec21034eb1079c2a222e7a0d2ab447de2c2392833baac3902713151c", "tests/test_grounded_candidates.py": "eacfca315f4d1046a3e23b5fc12213c8e75167a56d4cf58acd95a5224d0c2a5f", "tests/test_image_classification_export.py": "f1a93a4c638a563cd481668b80d05ed48b0a57e58f021cccf8c3ded5c3d06e44", "tests/test_image_generation.py": "2c4dc04957f25497c7b84cf4870efeba85f171aabbbc9c798ead0ee36c554e7f", "tests/test_image_training.py": "1a1dcb3bf330ab3b9790cfbccbddebc5444e2c8703403cc40b5e3e81e882b01d", "tests/test_instruction_responses.py": "f6754faa43b35b43839ac968acd7c05a2197576ff4e355e237e783a992ba0d7d", "tests/test_mesh_release.py": "cc57a6d4b58cd96551d25a46631945a45c7dc39a21a869e563068a021ec89c20", "tests/test_mesh_runs.py": "f03b012c0fa7649fb25ab2464977980066fa886fb26fc417111e802dcab47267", "tests/test_meshes.py": "d9d36438aba8cce733e4a7a67559ea45095b797311d53392089389d0b1de5d38", "tests/test_metadata_filters.py": "fef2682f8c6a2e7d1ed58dc08fba8d653edd98a76578d7cc012841a959b25631", "tests/test_metadata_migration.py": "9de22c42dddf41066586bbde1c6852ad09bdb1730a3ce9a25826658924046e9c", "tests/test_metadata_transactions.py": "14d9155639c6d613c75be318effe7413be14998c848c455cd92c87d266623c4c", "tests/test_metadata_workers.py": "fd9b624410ad3d32aea5bc77b3739a9aa8207f6d9a0da3bec27b0f54d72462c5", "tests/test_native_detection_import.py": "2eb4e8ab069bf2636ce9cfb17c2ed7286d82349324f8a073037906aa9c59a751", "tests/test_native_detection_stack.py": "5e8e2e955f9b6ae0b0f702cd48fea922995bcfc296783df1abbe152836d69b25", "tests/test_native_text_import.py": "86d347c27587214062a6cf7a0d1d8799d4422818117a6cc9e26b1bf90aff69d0", "tests/test_pipeline.py": "bda005471eafc061482990a59d16ce91924bbf46e31b1a0f2a766e16be694bbc", "tests/test_pointclouds.py": "4551a41de6f0d45bd123c8d640324613e698e1683c9a663fa0a47c07f1cefa9e", "tests/test_preferences.py": "f3c6591965b9a14e4623940ad02696339452ddd0910ffdff4d617ce1b40e28dd", "tests/test_projects.py": "29fa8a8a421a764a13605a087a6432b7671b01a5ba6511948beadf112b9b7d2e", "tests/test_pumas_gateways.py": "c716d118e3e6ba0723f7751eb20b6c5cd496b3590f0e82d3341b150e9457621a", "tests/test_pumas_typed.py": "9b53bd8792b1b2330bc326f626cc3f91e050a7d9687c512018c35c110b2d5edf", "tests/test_pumas_vision.py": "0bc9d1d055ab60167fbf808cfa83e63b7a9e59694dd51bc00602218632bc54d4", "tests/test_qa_qualification.py": "539abd5c349b2fd899cab9dd4b64d618d9e0012eaf2f06a5bdb2e8bec795f599", "tests/test_real_import_foundation.py": "92c10da87b4c0a6593ff0546f9a89656ad2516b590e1a5cde903785a46731b12", "tests/test_recipe_contract.py": "fea5aa61743d4f020cee85195ce24de1a9cf7f1dd3501be074f1715034223f78", "tests/test_recipe_process.py": "1c02ed5f2188edc9b83dfecea42667dfd4cc2b46d8c6181226ebcca60c49e626", "tests/test_release_preview.py": "ee8f1f2701c4cddc7d0c7fdd211894428620f0415d8caf0bbdc931a7e7936f79", "tests/test_rights_note.py": "fbffc75b8651f739e1b98989e7c8e4708260580a73471a70d7d1b15e00b857b6", "tests/test_runs.py": "15e0342e5f7b146c6cb70a28816756b9e1348b0ab152440ae32882c67e4eb501", "tests/test_saved_generation.py": "546ea3db08c0d772a3616f4dc00757b2cd0c6c14ad056f5783527d391a122a5a", "tests/test_saved_searches.py": "fc3f5b0a12835be2fa629e1622ab1413bdbae7cf7c3632caf7a5225fdb277300", "tests/test_saved_selections.py": "560a1fcb6766abfa706dc642c73b8d91fb171a3e007e49604163f281f906dc8a", "tests/test_scientific_fields.py": "868b4294fe3aaa258796a562eed44b49e49f29585e05107e9e2ce7a21b908154", "tests/test_scientific_release.py": "f1c5a57dfd76f5758c9cf55f47c68c545a2483e971dcc041056fed12a2beb79f", "tests/test_sequence_batch.py": "c8be7c857d37ca11d8e52878115eea5c93a21e7baa50ec2261c1a1fc1a6b7054", "tests/test_sequence_release.py": "a7457466674f48bb08cde5237b80d5ca770128b22f5f359ecd4bc90d12d30819", "tests/test_sequence_runs.py": "09b9861d05f0a5dc0b9da2390f1eff63dba25662ae599fd0ae59e7b7fddbf53a", "tests/test_sequence_v2_runs.py": "c0a01076f9869f366bd9de96f6b8e338a747d8abc5a1867ab6cdab88869f6e5e", "tests/test_sequences.py": "0e305b0eeb718893e857a355998345137fe043c5cbce46b29b91046e91d15688", "tests/test_sequences_v2.py": "ebf96c2cf91e7e05e780f5d46f53f0eb98fc13cc197af818628ec8cd34958f40", "tests/test_spatial_release.py": "823cd95654cfa8be17f07b6e6c84fe00b03024beee81f8ca9f5a3cbfa051f49d", "tests/test_spatial_runs.py": "59d1c53542e15cfeb78922be8e366aaec2db541a7a1cbb69710ade249951a99b", "tests/test_spatial_storage.py": "dc9e0588b73b5fc03b296d1382c4e131571dd1b261c2424f4beff15b0ddaccb0", "tests/test_synthetic.py": "7d077c66a532efd57ea29347641f7962b4687baa664b5d339a0ed2b1223fcd52", "tests/test_text_classification_proposals.py": "7ecf4870d58e915dbcf74546e531ad28939eb837170401e88f07346ae4de51b3", "tests/test_text_corpus_export.py": "c8f840ec9263c9e8f70b0e93da9632d1d1258b0690718ded9b3685ed9a3145c7", "tests/test_text_training.py": "94481a278c29a056018fa27585ca712ea38ba7ba57663628ae4be10022ee374b", "tests/test_volume_assets.py": "11519cefc7c0bffba7f878336465f2e16b5b70b65cd480f5326bb06afa4acbfd", "tests/test_workbench.py": "97fd968831531fc750f564f3e23dc3b021662a4d955939e82f5048dd87c69ef5", "tests/test_workspace_contracts.py": "b281d64940892b0408702b0b6fa1346daec018fcbfbb5b75ef955158bd8b6f41", "tests/test_workspace_metadata.py": "3bc9a6823935329588d0eee7d2ddf6960ff4bd4d12df9cd736d19badb2cd4ac5", "tests/test_workspace_offline.py": "03a277e830dd8c5a2947d2158276b9207b675ae7c75f2562f3e6172acd93eb4b", "text_classification_export.py": "2510ad278a95892d4453ffb5b146ae47c11f8e31f3dc4cf9fb005eec79270bdf", "text_classification_proposals.py": "6a29dfe752be4ae2c69d7b2e4ca3e68e87dc511cfee2429093748b4ccc56c86d", "text_corpus_export.py": "3af4883df1b714519fb4e9be872f39de20dc3013deca720e32a89789cbdbff69", "text_training.py": "9794c343af00854519be0873bad766eadf681c4826be010efb3423cae1d0974e", "upgrade_metadata.py": "df798ada0b929fd329c42add8545109422b5821874aeb4c913c4ef5290015525", "volume_assets.py": "1e057fcec996969e0a9b44ae7561fb7b6ea95b6201a23617fdbbc3a046b610c1", "workbench.py": "71bbbaf56ae138c5a80ef4ee9854851470bae5effd20315c8fc4febc795fa643"} \ No newline at end of file diff --git a/docs/plans/generic-scientific-projects/reports/p3b/receipt.json b/docs/plans/generic-scientific-projects/reports/p3b/receipt.json new file mode 100644 index 00000000..ff166663 --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b/receipt.json @@ -0,0 +1,45 @@ +{ + "source_commit": "c8ba1ad59e2089f37c4876998066d70cd81da4fc", + "qualification": "Neutral real process/descendant and artifact custody only; no scientific/model acceptance", + "checks": [ + "Real keyboard-created edited graph, exact review, stale-byte refusal, descendant execution and exact artifact custody", + "Owner creates an exact-material one-use grant; separately authenticated agent executes it without owner review controls", + "Cloned graph cancellation waits for confirmed custody termination", + "Server restart retains exact completed run and downloadable original output" + ], + "captures": [ + { + "file": "external-pipeline-1440.jpg", + "width": 1440, + "height": 900, + "selector": "#external-material", + "qualification": "Neutral process execution only; no scientific qualification" + }, + { + "file": "external-pipeline-390.jpg", + "width": 390, + "height": 900, + "selector": "#external-material", + "qualification": "Neutral process execution only; no scientific qualification" + }, + { + "file": "external-runs-390.jpg", + "width": 390, + "height": 900, + "selector": ".external-run-custody", + "qualification": "Neutral process execution only; no scientific qualification" + }, + { + "file": "external-runs-1440.jpg", + "width": 1440, + "height": 900, + "selector": ".external-run-custody", + "qualification": "Neutral process execution only; no scientific qualification" + } + ], + "run_id": "c2655e8848944df29326f5d1a901fbb0", + "input_sha256": "1e4e0965a0a773437c393cfcd99d6c3794d6092fb22ba929f8557e822f653b68", + "browser": "Chrome/151.0.7922.173", + "source_state": "Portability follow-up worktree based on source_commit; exact changed files pinned in source-files.json.", + "source_inventory_sha256": "514f6974e4b866b5ef1831e18a3c7d3b633342deb7fdb9b9cb88f26df8ebea1c" +} diff --git a/docs/plans/generic-scientific-projects/reports/p3b/source-files.json b/docs/plans/generic-scientific-projects/reports/p3b/source-files.json new file mode 100644 index 00000000..918a45fb --- /dev/null +++ b/docs/plans/generic-scientific-projects/reports/p3b/source-files.json @@ -0,0 +1,31 @@ +{ + ".github/workflows/tests.yml": "756ea1e4d34fa056cd1112da35c0dd02c492d7fa9026f1feea6aaad840c5eacc", + "README.md": "edd92af6f3fd4ddb8ba0dc4c964119e60820a77b4d0f85ad648a6438da53671b", + "access.py": "cbf1d2016b43cc85747fefe12da041ebb74004395b833492340fa7ae036183e4", + "app.py": "589c2185cbbc512cc2907fd086f38a91749d3665afa61e29a0707242069d2810", + "metadata.py": "42559a7efd599f637e6e289802fa7400d59b2915edcf64e3260952d59cd7b439", + "pipeline.py": "030b08b215b37701ec2b9a4f00240edef05213191b9568abdb2f2f013ae84659", + "projects.py": "d147c6bae61068f5517fd15e3512311459cd4de3d6edfdd9ea984783470d432d", + "recipe_contract.py": "a1f8c3a401d1c580ab6428d813792fb25c9533a4e66919b88cc24aa13c1e175c", + "recipe_process.py": "f73d0881c9c3d509616e11e783a65e2bce2b9eeb9afa467602b953c93d0298f5", + "runs.py": "3237db72da8461fa6154955382a95290c1834448812ca00b0443d9c8025dfc3a", + "static/workspace-external.js": "62c2020b9aea1cf240adaf484c343de4fc8bf51539e6e31c5bf50c6831d73eb2", + "static/workspace-projects.js": "4a5e2e4c61cea0cf9f3a30772cf5f47408c72a77d6fe2afe63a2717e83157b7a", + "static/workspace-real.js": "18cd614005b33f8b84084531ebcc3ead00f3c76aeaeb28e4a098dae3c7960f1c", + "static/workspaces.css": "a8152b6da7deb3a8ce65a0de50f0854ed762058954e0015488cc680438bdde60", + "static/workspaces.html": "b68e85cb8d06055506d34c691896915fb7adf62d4c669a3d558299db5e6a0fac", + "static/workspaces.js": "0b9731dd557e1e92cc7cac2ffbac369a38e116b021541ce742fc7df8bb35c18d", + "tests/browser_workspace_external.cjs": "56f1c7485c4b6fc1181317df93bd370584250426f46c7c6568e1182f7237f8fb", + "tests/browser_workspace_recovery.cjs": "6508a410717032d2806588504e756325358503a60fc0144c186f1058f612b568", + "tests/fixtures/external_recipe.py": "06815b425a7722e0aa64d0c8739263fc2db371027b382d0c3326691305e1879c", + "tests/test_access.py": "d135a0556a53fc5d173b8d3b4561e9f5d28d47defee299dbca2aff2cab7356e3", + "tests/test_execution_approvals.py": "8368601c1cdb90504533e7f88a515101e7362ac780380224fac8a925c936bb2b", + "tests/test_external_http.py": "dff9afebade39bc530575f19defbe6064ac39b5406a9e461fca7f1af6cf6e72c", + "tests/test_external_runs.py": "59931dd73ebe7531e793a6dbe5ac4f9f9d5a6c8d6eb2df83930611d7e99118a4", + "tests/test_recipe_contract.py": "84a3e0fb10f53ae1462c1c8af8a36f9f30966d9afc754b18e4a9a856e9ae8614", + "tests/test_recipe_process.py": "1c02ed5f2188edc9b83dfecea42667dfd4cc2b46d8c6181226ebcca60c49e626", + "tests/test_spatial_storage.py": "dc9e0588b73b5fc03b296d1382c4e131571dd1b261c2424f4beff15b0ddaccb0", + "tests/test_workspace_external_controller.cjs": "26878dbc44960885f18ecb1618a10d3d3235b316ecff1cf675334af36f5af350", + "tests/test_workspace_metadata.py": "3bc9a6823935329588d0eee7d2ddf6960ff4bd4d12df9cd736d19badb2cd4ac5", + "upgrade_metadata.py": "df798ada0b929fd329c42add8545109422b5821874aeb4c913c4ef5290015525" +} diff --git a/metadata.py b/metadata.py index 48f97ac9..93d84a7a 100644 --- a/metadata.py +++ b/metadata.py @@ -19,8 +19,8 @@ from psycopg import sql from psycopg.conninfo import conninfo_to_dict -SCHEMA_VERSION = 7 -SUPPORTED_SCHEMA_VERSIONS = (1, 2, 3, 4, 5, 6, 7) +SCHEMA_VERSION = 8 +SUPPORTED_SCHEMA_VERSIONS = (1, 2, 3, 4, 5, 6, 7, 8) MANIFEST = '.tuldok.json' CATALOG_VERSION_DDL = '''CREATE TABLE catalog_version ( version INTEGER PRIMARY KEY, dataset_id TEXT NOT NULL, @@ -415,7 +415,7 @@ def close(self): def tables_for_version(version): if type(version) is not int or version not in SUPPORTED_SCHEMA_VERSIONS: raise StorageError('Unsupported PostgreSQL catalog version.') - return {1: TABLES_V1, 2: TABLES_V2, 3: TABLES_V3, 4: TABLES_V4, 5: TABLES_V5, 6: TABLES_V6, 7: TABLES}[version] + return {1: TABLES_V1, 2: TABLES_V2, 3: TABLES_V3, 4: TABLES_V4, 5: TABLES_V5, 6: TABLES_V6, 7: TABLES_V7, 8: TABLES}[version] def definition_hash(version=SCHEMA_VERSION): @@ -550,4 +550,14 @@ def definition_hash(version=SCHEMA_VERSION): id TEXT PRIMARY KEY, catalog_id TEXT NOT NULL, actor_id TEXT NOT NULL, credential_id TEXT NOT NULL, kind TEXT NOT NULL, job_id TEXT NOT NULL, request_digest TEXT NOT NULL, effects_json TEXT NOT NULL, created_at BIGINT NOT NULL)''', } -TABLES = {**TABLES_V6, **ACCESS_TABLES} +TABLES_V7 = {**TABLES_V6, **ACCESS_TABLES} +EXECUTION_APPROVAL_TABLES = { + 'access_execution_grants': '''CREATE TABLE access_execution_grants ( + id TEXT PRIMARY KEY, catalog_id TEXT NOT NULL, approver_actor_id TEXT NOT NULL, + approver_credential_id TEXT NOT NULL, consumer_actor_id TEXT NOT NULL, material_sha256 TEXT NOT NULL, + created_at BIGINT NOT NULL, expires_at BIGINT NOT NULL, revoked_at BIGINT)''', + 'access_execution_consumptions': '''CREATE TABLE access_execution_consumptions ( + grant_id TEXT PRIMARY KEY, run_id TEXT UNIQUE NOT NULL, admission_id TEXT UNIQUE NOT NULL, + consumer_credential_id TEXT NOT NULL, request_sha256 TEXT NOT NULL, consumed_at BIGINT NOT NULL)''', +} +TABLES = {**TABLES_V7, **EXECUTION_APPROVAL_TABLES} diff --git a/pipeline.py b/pipeline.py index a27f7157..c611010a 100644 --- a/pipeline.py +++ b/pipeline.py @@ -21,6 +21,7 @@ import text_training import audio_training import release_validation +import recipe_contract ID = re.compile(r'^[a-f0-9]{32}$') HASH = re.compile(r'^[a-f0-9]{64}$') @@ -60,7 +61,8 @@ def decode_graph(value): closed(value, ('schema_version', 'mode', 'id', 'revision', 'name', 'recipe_version', 'nodes', 'edges'), ('layout', 'recipe')) if value['schema_version'] != 1 or type(value['schema_version']) is not int or value['mode'] != 'real': raise WorkbenchError('Only real graph schema 1 is supported; fixture graphs cannot execute.', 'unsupported', 400) - adapter_for_graph(value) + if value.get('recipe') != 'external_recipe': + adapter_for_graph(value) identifier(value['id'], 'Graph ID') if type(value['revision']) is not int or value['revision'] < 1 or value['recipe_version'] != 1 or type(value['recipe_version']) is not int: raise WorkbenchError('Invalid graph or recipe revision.') @@ -194,6 +196,54 @@ def list(self): ids = [row[0] for row in self.db.execute('SELECT id FROM workspace_graphs ORDER BY id')] return [self._get(graph_id) for graph_id in ids] + @authorized('inspect', 'pipeline.inspect_external_recipe') + def inspect_external_recipe(self, project_id, reference_id, expected_sha256): + return recipe_contract.inspect_recipe(self.dataset.projects, project_id, reference_id, expected_sha256) + + @authorized('edit', 'pipeline.create_external') + def create_external(self, body): + closed(body, ('name', 'project_id', 'recipe_id', 'expected_sha256', 'inputs'), ('parameters',)) + inspected = self.inspect_external_recipe(body['project_id'], body['recipe_id'], body['expected_sha256']) + parameters = recipe_contract.validate_parameters(inspected['definition'], body.get('parameters', {})) + config = {key: body[key] for key in ('project_id', 'recipe_id', 'expected_sha256', 'inputs')} + graph = {'schema_version':1, 'mode':'real', 'recipe':'external_recipe', 'recipe_version':1, + 'id':uuid.uuid4().hex, 'revision':1, 'name':text_value(body['name'], 'Recipe name', 120), + 'nodes':[{'id':name,'type':name,'definition_version':1, + 'parameters':config if name == 'input' else parameters if name == 'execute' else {}} + for name in recipe_contract.TYPES], + 'edges':[{'from':a,'output':recipe_contract.PORTS[a][1],'to':b,'input':recipe_contract.PORTS[b][0]} + for a,b in zip(recipe_contract.TYPES,recipe_contract.TYPES[1:])], 'layout':{}} + graph = decode_graph(graph) + with self.lock, self.db.transaction(): + self.db.execute('INSERT INTO workspace_graphs(id,revision,document) VALUES(%s,%s,%s)', + (graph['id'], 1, encode(graph))) + self.access.audit('pipeline.create_external', graph['id'], + {'revision':1,'document_sha256':digest(graph),'execution_sha256':execution_digest(graph)}) + return graph + + @authorized('inspect', 'pipeline.preflight_external') + def preflight_external(self, graph_id, revision): + graph = self.get(graph_id) + if graph.get('recipe') != 'external_recipe' or type(revision) is not int or graph['revision'] != revision: + raise WorkbenchError('External graph changed or is unavailable.', 'stale', 409) + result, _captured = recipe_contract.prepare(self.dataset.projects, graph, execution_digest(graph), + getattr(self.dataset, 'external_runtime_profile', None)) + if self.get(graph_id) != graph: + raise WorkbenchError('Graph changed during preflight.', 'stale', 409) + return result + + @authorized('inspect', 'pipeline.capture_external') + def capture_external(self, graph_id, revision, expected_digest, staging): + self.access.require_external_submission() + graph = self.get(graph_id) + if graph.get('recipe') != 'external_recipe' or type(revision) is not int or graph['revision'] != revision: + raise WorkbenchError('External graph changed or is unavailable.', 'stale', 409) + result, captured = recipe_contract.prepare(self.dataset.projects, graph, execution_digest(graph), + getattr(self.dataset, 'external_runtime_profile', None)) + if expected_digest != result['material_sha256'] or self.get(graph_id) != graph: + raise WorkbenchError('Reviewed execution material changed. Preflight again.', 'stale', 409) + return dict(recipe_contract.capture(result, captured, staging), graph=graph) + @authorized('edit', 'pipeline.create') def create(self, body): closed(body, ('name', 'release_id'), ('recipe',)) @@ -396,6 +446,10 @@ def definition_identity(self, recipe='image_classification'): @authorized('inspect', 'pipeline.validate_graph', target=lambda graph: graph.get('id') if isinstance(graph, dict) else None) def validate_graph(self, graph): graph = decode_graph(graph) + if graph.get('recipe') == 'external_recipe': + result, _captured = recipe_contract.prepare(self.dataset.projects, graph, execution_digest(graph), + getattr(self.dataset, 'external_runtime_profile', None)) + return dict(result, errors=[], release=None) adapter = adapter_for_graph(graph) ports = ports_for_graph(graph) types = types_for_graph(graph) diff --git a/projects.py b/projects.py index d5b89513..847364d3 100644 --- a/projects.py +++ b/projects.py @@ -284,6 +284,51 @@ def read_data_reference(self, project_id, reference_id, expected_sha256, limit): return raw, {'project_id': project_id, 'manifest_sha256': saved['manifest_sha256'], 'reference_id': reference_id, 'path': ref['path'], 'measured_sha256': digest} + @authorized('inspect', 'projects.read_recipe_reference') + def read_recipe_reference(self, project_id, reference_id, expected_sha256): + if not isinstance(expected_sha256, str) or not SHA.fullmatch(expected_sha256): + raise WorkbenchError('Select the observed recipe SHA256.') + saved = self._saved(project_id) + if not self._bound(saved): + raise WorkbenchError('Original project root is not configured.', 'unavailable', 409) + ref = next((entry for entry in saved['manifest']['recipes'] if entry['id'] == reference_id), None) + if ref is None: + raise WorkbenchError('Recipe reference not found.', 'not_found', 404) + try: + raw = self._read(saved['root'], ref['path'], 65536) + except OSError: + raise WorkbenchError('Recipe definition cannot be safely read.', 'unavailable', 409) from None + measured = hashlib.sha256(raw).hexdigest() + if measured != expected_sha256 or ref.get('sha256', measured) != measured: + raise WorkbenchError('Recipe changed. Inspect its definition again.', 'stale', 409) + return raw, {'project_id': project_id, 'manifest_sha256': saved['manifest_sha256'], + 'reference_id': reference_id, 'path': ref['path'], 'measured_sha256': measured} + + @authorized('inspect', 'projects.read_recipe_sources') + def read_recipe_sources(self, project_id, sources): + saved = self._saved(project_id) + if not self._bound(saved): + raise WorkbenchError('Original project root is not configured.', 'unavailable', 409) + if not isinstance(sources, list) or not 1 <= len(sources) <= 64: + raise WorkbenchError('Declare 1–64 bounded source files.') + result, total = {}, 0 + for source in sources: + closed(source, ('path', 'sha256')) + path = relative_path(source['path']) + if path in result: + raise WorkbenchError('Repeated source path.') + try: + raw = self._read(saved['root'], path, FILE_LIMIT) + except OSError: + raise WorkbenchError('Recipe source cannot be safely read.', 'unavailable', 409) from None + total += len(raw) + if total > INSPECTION_LIMIT: + raise WorkbenchError('Source closure exceeds 64 MiB.') + if hashlib.sha256(raw).hexdigest() != source['sha256']: + raise WorkbenchError('Recipe source changed; update and review its definition.', 'stale', 409) + result[path] = raw + return result + @authorized('inspect', 'projects.evidence') def evidence(self, project_id, reference_id): saved = self._saved(project_id) diff --git a/recipe_contract.py b/recipe_contract.py new file mode 100644 index 00000000..a27e4111 --- /dev/null +++ b/recipe_contract.py @@ -0,0 +1,429 @@ +"""Declarative trusted-local recipes: bounded capture, never import or execute.""" +import base64 +import hashlib +import os +from pathlib import Path +import re +import stat +import struct + +from projects import closed, decode, relative_path +from workbench import WorkbenchError, encode + +NAME = re.compile(r'[A-Za-z][A-Za-z0-9_-]{0,63}') +SHA = re.compile(r'[a-f0-9]{64}') +MAX_SOURCE_BYTES = 8 * 1024 * 1024 +MAX_CAPTURE_BYTES = 64 * 1024 * 1024 +MAX_FILES = 128 +RUNTIME_LIMIT = 512 * 1024 * 1024 +TYPES = ('input', 'execute', 'output') +PORTS = {'input': (None, 'data'), 'execute': ('data', 'artifacts'), 'output': ('artifacts', None)} +TRUST = 'Trusted local code; filesystem and network are not sandboxed. Runtime installation must remain immutable for the attempt.' +HOST_NAMES = ('recipe_contract.py', 'projects.py', 'pipeline.py', 'recipe_process.py') +IMPORTED_HOST_FILES = {name: hashlib.sha256((Path(__file__).resolve().parent/name).read_bytes()).hexdigest() for name in HOST_NAMES} + + +def digest(value): + return hashlib.sha256(encode(value).encode()).hexdigest() + + +def file_digest(raw): + return hashlib.sha256(raw).hexdigest() + + +def bounded_int(value, low, high, label): + if type(value) is not int or not low <= value <= high: + raise WorkbenchError(label + ' is outside its supported integer bounds.') + return value + + +def named(value): + if not isinstance(value, str) or not NAME.fullmatch(value): + raise WorkbenchError('Recipe names must use bounded letters, digits, underscore or hyphen.') + return value + + +def decode_definition(raw): + if len(raw) > 65536: + raise WorkbenchError('Recipe definition exceeds 64 KiB.') + value = decode(raw) + closed(value, ('schema_version', 'format', 'id', 'name', 'version', 'runtime', 'sources', 'entrypoint', + 'arguments', 'parameters', 'inputs', 'outputs', 'environment', 'resources')) + if type(value['schema_version']) is not int or value['schema_version'] != 1 or value['format'] != 'external_recipe_v1': + raise WorkbenchError('Only external_recipe_v1 is supported.', 'unsupported', 400) + named(value['id']) + bounded_int(value['version'], 1, 1, 'Recipe version') + if not isinstance(value['name'], str) or not 1 <= len(value['name']) <= 120: + raise WorkbenchError('Supply a bounded recipe name.') + if value['runtime'] != 'system_python': + raise WorkbenchError('Only the configured system_python runtime is qualified.', 'unsupported', 400) + sources = value['sources'] + if not isinstance(sources, list) or not 1 <= len(sources) <= 64: + raise WorkbenchError('Declare 1–64 source files.') + paths = set() + for source in sources: + closed(source, ('path', 'sha256')) + path = relative_path(source['path']) + if path in paths or not isinstance(source['sha256'], str) or not SHA.fullmatch(source['sha256']): + raise WorkbenchError('Source paths must be unique with explicit SHA256 hashes.') + paths.add(path) + if not isinstance(value['entrypoint'], str) or value['entrypoint'] not in paths: + raise WorkbenchError('Entrypoint must be one declared captured source.') + if not isinstance(value['parameters'], dict) or len(value['parameters']) > 32: + raise WorkbenchError('Declare at most 32 typed parameters.') + for key, rule in value['parameters'].items(): + named(key) + closed(rule, ('type', 'default'), ('min', 'max', 'enum', 'max_length')) + kind = rule['type'] + if kind not in ('integer', 'number', 'boolean', 'string'): + raise WorkbenchError('Unsupported parameter type.') + allowed = {'type', 'default'} | ({'min', 'max'} if kind in ('integer', 'number') else {'max_length', 'enum'} if kind == 'string' else set()) + if set(rule) - allowed: + raise WorkbenchError('Parameter constraints differ from its declared type.') + if kind in ('integer', 'number'): + import math + if not all(type(rule.get(k)) in (int, float) and math.isfinite(rule[k]) for k in ('min', 'max')) or rule['min'] > rule['max']: + raise WorkbenchError('Numeric parameters require finite ordered bounds.') + if kind == 'string': + bounded_int(rule.get('max_length'), 1, 1024, 'String length') + if 'enum' in rule and (not isinstance(rule['enum'], list) or not 1 <= len(rule['enum']) <= 64 or any(not isinstance(x, str) for x in rule['enum'])): + raise WorkbenchError('String choices must be a bounded list.') + validate_parameters(value, {}) + if not isinstance(value['inputs'], dict) or len(value['inputs']) > 32: + raise WorkbenchError('Declare at most 32 named inputs.') + for key, rule in value['inputs'].items(): + named(key); closed(rule, ('max_bytes',)) + bounded_int(rule['max_bytes'], 1, 40 * 1024 * 1024, 'Input bytes') + if not isinstance(value['arguments'], list) or len(value['arguments']) > 59: + raise WorkbenchError('Declare at most 59 argument tokens plus the fixed runtime entrypoint.') + for token in value['arguments']: + if not isinstance(token, dict) or len(token) != 1: + raise WorkbenchError('Arguments are single typed tokens.') + kind, arg = next(iter(token.items())) + if kind == 'literal': + if not isinstance(arg, str) or len(arg) > 1024 or '\0' in arg: + raise WorkbenchError('Literal argument is invalid.') + elif kind == 'parameter': + if not isinstance(arg, str) or arg not in value['parameters']: raise WorkbenchError('Unknown parameter argument.') + elif kind == 'input': + if not isinstance(arg, str) or arg not in value['inputs']: raise WorkbenchError('Unknown input argument.') + elif kind == 'source': + if not isinstance(arg, str) or arg not in paths: raise WorkbenchError('Unknown source argument.') + elif kind != 'output_dir' or arg is not True: + raise WorkbenchError('Unsupported argument token.') + outputs = value['outputs'] + if not isinstance(outputs, list) or not 1 <= len(outputs) <= 32: + raise WorkbenchError('Declare 1–32 output files.') + seen = set() + for output in outputs: + closed(output, ('path', 'role', 'max_bytes', 'required')) + path = relative_path(output['path']); named(output['role']) + if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,119}', path) or path in ('artifact-manifest.json', 'custody-receipt.json'): + raise WorkbenchError('Output must use an unreserved flat filename.') + if path in seen or type(output['required']) is not bool: raise WorkbenchError('Invalid output contract.') + seen.add(path) + bounded_int(output['max_bytes'], 1, MAX_CAPTURE_BYTES, 'Output bytes') + if value['environment'] != {}: + raise WorkbenchError('Initial runtime admits no project environment overrides.', 'unsupported', 400) + closed(value['resources'], ('wall_seconds', 'max_output_bytes')) + bounded_int(value['resources']['wall_seconds'], 1, 600, 'Wall seconds') + bounded_int(value['resources']['max_output_bytes'], 1, MAX_CAPTURE_BYTES, 'Output bytes') + return value + + +def validate_parameters(definition, values): + import math + rules = definition['parameters'] + if not isinstance(values, dict) or set(values) - set(rules): + raise WorkbenchError('Unknown recipe parameters.') + result = {} + for key, rule in rules.items(): + value = values.get(key, rule['default']); kind = rule['type'] + valid = ((type(value) is bool) if kind == 'boolean' else + (type(value) is int and rule['min'] <= value <= rule['max']) if kind == 'integer' else + (type(value) in (int, float) and math.isfinite(value) and rule['min'] <= value <= rule['max']) if kind == 'number' else + (isinstance(value, str) and len(value) <= rule['max_length'] and '\0' not in value and ('enum' not in rule or value in rule['enum']))) + if not valid: raise WorkbenchError('Invalid value for parameter ' + key + '.') + result[key] = value + return result + + +def _elf_dependencies(raw): + """Read ELF64 little-endian dynamic names without executing loader discovery.""" + if raw[:4] != b'\x7fELF': return [] + if raw[4:6] != b'\x02\x01': raise WorkbenchError('Runtime ELF layout is unsupported.') + offset = struct.unpack_from('= length: raise WorkbenchError('Invalid runtime dynamic names.') + end = raw.find(b'\0', base+at, base+length) + if end < 0: raise WorkbenchError('Invalid runtime dynamic name.') + result.append(raw[base+at:end].decode()) + break + else: raise WorkbenchError('Missing runtime string table.') + return result + + +def runtime_identity(profile=None): + """Finite trusted installation closure; no process launch or project discovery.""" + profile = profile or {'executable': '/usr/bin/python3', 'trusted_install_owner_uid': os.stat('/usr').st_uid} + closed(profile, ('executable', 'trusted_install_owner_uid')) + uid = profile['trusted_install_owner_uid'] + if type(uid) is not int or uid == os.getuid() or uid != os.stat('/usr').st_uid: + raise WorkbenchError('Runtime installation owner is unqualified.', 'unsupported', 409) + executable = Path(profile['executable']).resolve(strict=True) + if executable.parent != Path('/usr/bin') or not re.fullmatch(r'python3\.\d+', executable.name): + raise WorkbenchError('Runtime must be the configured system Python installation.', 'unsupported', 409) + library = Path('/usr/lib') / executable.name + if not library.is_dir(): raise WorkbenchError('System Python standard library is unavailable.', 'unavailable', 409) + pending = [executable] + for directory, dirs, files in os.walk(library, followlinks=False): + dirs[:] = sorted(dirs) + if any((Path(directory)/name).is_symlink() for name in dirs): + raise WorkbenchError('Runtime library directory symlinks are unsupported.') + for name in sorted(files): + pending.append(Path(directory)/name) + if len(pending) > 10000: raise WorkbenchError('Runtime closure exceeds file bound.') + files, total = {}, 0 + while pending: + path = pending.pop().resolve(strict=True) + if str(path) in files: continue + if not (path.is_relative_to('/usr') or path == Path('/etc') / executable.name / 'sitecustomize.py'): + raise WorkbenchError('Runtime dependency escapes trusted installation.') + for ancestor in (path, *path.parents): + if ancestor == Path('/'): break + info = ancestor.stat() + if info.st_uid != uid or info.st_mode & 0o022: + raise WorkbenchError('Runtime installation is writable or has a different owner.', 'unsupported', 409) + if ancestor in (Path('/usr'), Path('/etc')): break + info = path.stat() + if not stat.S_ISREG(info.st_mode) or info.st_size > 64 * 1024 * 1024: + raise WorkbenchError('Runtime dependency is not a bounded regular file.') + raw = path.read_bytes(); after = path.stat() + if (info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns) != (after.st_ino, after.st_size, after.st_mtime_ns, after.st_ctime_ns): + raise WorkbenchError('Runtime changed during preflight.', 'stale', 409) + total += len(raw) + if total > RUNTIME_LIMIT: raise WorkbenchError('Runtime closure exceeds byte bound.') + files[str(path)] = {'bytes': len(raw), 'sha256': file_digest(raw)} + for name in _elf_dependencies(raw): + if name.startswith('/'): + dependency = Path(name) + else: + if '/' in name: raise WorkbenchError('Runtime dependency has unsupported path.') + dependency = next((base/name for base in (Path('/usr/lib/x86_64-linux-gnu'), Path('/usr/lib')) if (base/name).exists()), None) + if dependency is None: raise WorkbenchError('Runtime dependency is missing: ' + name, 'unavailable', 409) + pending.append(dependency) + return {'profile': 'system_python', 'executable': str(executable), 'executable_sha256': files[str(executable)]['sha256'], + 'trusted_install_owner_uid': uid, 'files': dict(sorted(files.items())), 'closure_sha256': digest(files), + 'assumption': TRUST, 'flags': ['-I', '-S', '-B']} + + +def graph_parameters(graph): + nodes = graph['nodes'] + if len(nodes) != 3 or {n['type'] for n in nodes} != set(TYPES) or any(n['definition_version'] != 1 for n in nodes): + raise WorkbenchError('External graphs require exactly input, execute and output version-1 nodes.') + typed = {n['type']: n for n in nodes} + expected = [{'from':typed[a]['id'], 'output':PORTS[a][1], 'to':typed[b]['id'], 'input':PORTS[b][0]} for a,b in zip(TYPES,TYPES[1:])] + if sorted(map(encode, graph['edges'])) != sorted(map(encode, expected)) or typed['output']['parameters']: + raise WorkbenchError('Connect external input → execute → output exactly once.') + config = typed['input']['parameters'] + closed(config, ('project_id', 'recipe_id', 'expected_sha256', 'inputs')) + return config, typed['execute']['parameters'] + + +def inspect_recipe(projects, project_id, reference_id, expected_sha256): + raw, receipt = projects.read_recipe_reference(project_id, reference_id, expected_sha256) + definition = decode_definition(raw) + return {'definition': definition, 'receipt': receipt, 'parameter_definitions': definition['parameters'], + 'inputs': definition['inputs'], 'outputs': definition['outputs'], 'runtime': definition['runtime']} + + +def host_identity(): + import recipe_process + root = Path(__file__).resolve().parent + current = {name: file_digest((root/name).read_bytes()) for name in HOST_NAMES} + if current != IMPORTED_HOST_FILES or file_digest(recipe_process.SOURCE) != current['recipe_process.py']: + raise WorkbenchError('Execution host changed after import. Restart before preflight or execution.', 'stale', 409) + return current + + +def prepare(projects, graph, execution_sha256, profile=None): + config, values = graph_parameters(graph) + inspected = inspect_recipe(projects, config['project_id'], config['recipe_id'], config['expected_sha256']) + definition = inspected['definition']; values = validate_parameters(definition, values) + sources = projects.read_recipe_sources(config['project_id'], definition['sources']) + if not isinstance(config['inputs'], dict) or set(config['inputs']) != set(definition['inputs']): + raise WorkbenchError('Bind every declared input exactly once.') + captured = {'source/' + path: raw for path, raw in sources.items()} + inputs = {} + for name, binding in config['inputs'].items(): + closed(binding, ('reference_id', 'expected_sha256')) + raw, receipt = projects.read_data_reference(config['project_id'], binding['reference_id'], binding['expected_sha256'], definition['inputs'][name]['max_bytes']) + captured['input/' + name] = raw; inputs[name] = receipt + if len(captured) > MAX_FILES or sum(map(len,captured.values())) > MAX_CAPTURE_BYTES: + raise WorkbenchError('Captured source and input files exceed the total bound.') + try: + runtime = runtime_identity(profile) + except (OSError, struct.error, UnicodeError): + raise WorkbenchError('Qualified system runtime cannot be safely inspected.', 'unavailable', 409) from None + host = host_identity() + material = {'schema_version': 1, 'catalog_id': projects.db.dataset_id, 'project': inspected['receipt'], 'graph_execution_sha256': execution_sha256, + 'recipe': definition, 'parameters': values, 'inputs': inputs, + 'captures': {path: {'bytes':len(raw),'sha256':file_digest(raw)} for path,raw in sorted(captured.items())}, + 'runtime': runtime, 'host_files': host, 'permissions': {'filesystem':'trusted-local', 'network':'not_isolated'}, + 'environment': {'LANG':'C.UTF-8'}, 'resources': definition['resources']} + return {'valid':True, 'status':'valid', 'material':material, 'material_sha256':digest(material), 'validation_token':digest(material), + 'parameter_definitions':definition['parameters'], 'outputs':definition['outputs'], 'runtime':runtime, + 'graph_revision':graph['revision'], 'execution_sha256':execution_sha256}, captured + + +def validate_material(material): + """Cold structural custody checks; no filesystem access or current-code comparison.""" + closed(material, ('schema_version', 'catalog_id', 'project', 'graph_execution_sha256', 'recipe', + 'parameters', 'inputs', 'captures', 'runtime', 'host_files', 'permissions', 'environment', 'resources')) + if type(material['schema_version']) is not int or material['schema_version'] != 1 or not isinstance(material['catalog_id'], str) or not material['catalog_id']: + raise WorkbenchError('Invalid execution material identity.') + def sha(value): + if not isinstance(value, str) or not SHA.fullmatch(value): raise WorkbenchError('Invalid material SHA256.') + def receipt(value): + closed(value, ('project_id', 'manifest_sha256', 'reference_id', 'path', 'measured_sha256')) + if not isinstance(value['project_id'], str) or not re.fullmatch('[a-f0-9]{32}', value['project_id']): raise WorkbenchError('Invalid material project identity.') + if not isinstance(value['reference_id'], str) or not re.fullmatch('[A-Za-z0-9][A-Za-z0-9_.-]{0,63}', value['reference_id']): raise WorkbenchError('Invalid reference identity.') + relative_path(value['path']); sha(value['manifest_sha256']); sha(value['measured_sha256']) + sha(material['graph_execution_sha256']); receipt(material['project']) + definition = decode_definition(encode(material['recipe']).encode()) + if encode(validate_parameters(definition, material['parameters'])) != encode(material['parameters']): + raise WorkbenchError('Retained parameters must include every typed value.') + if material['resources'] != definition['resources'] or material['environment'] != {'LANG':'C.UTF-8'} or material['permissions'] != {'filesystem':'trusted-local', 'network':'not_isolated'}: + raise WorkbenchError('Material execution policy is inconsistent.') + if not isinstance(material['inputs'], dict) or set(material['inputs']) != set(definition['inputs']): raise WorkbenchError('Material input inventory differs.') + expected = {'source/'+item['path']:item['sha256'] for item in definition['sources']} + for name, item in material['inputs'].items(): + receipt(item) + if (item['project_id'], item['manifest_sha256']) != (material['project']['project_id'], material['project']['manifest_sha256']): + raise WorkbenchError('Input receipt belongs to another project snapshot.') + expected['input/'+name] = item['measured_sha256'] + captures = material['captures'] + if not isinstance(captures, dict) or set(captures) != set(expected) or len(captures) > MAX_FILES: + raise WorkbenchError('Captured inventory differs from the declared source and inputs.') + total = 0 + for path, item in captures.items(): + relative_path(path); closed(item, ('bytes','sha256')); sha(item['sha256']) + limit = MAX_SOURCE_BYTES if path.startswith('source/') else definition['inputs'][path.split('/',1)[1]]['max_bytes'] + bounded_int(item['bytes'],0,limit,'Capture bytes'); total += item['bytes'] + if item['sha256'] != expected[path]: raise WorkbenchError('Captured digest contradicts source/input identity.') + if total > MAX_CAPTURE_BYTES: raise WorkbenchError('Captured material exceeds byte bound.') + runtime = material['runtime'] + closed(runtime, ('profile','executable','executable_sha256','trusted_install_owner_uid','files','closure_sha256','assumption','flags')) + if runtime['profile'] != 'system_python' or runtime['flags'] != ['-I','-S','-B'] or not isinstance(runtime['executable'],str) or not re.fullmatch(r'/usr/bin/python3\.\d+',runtime['executable']): + raise WorkbenchError('Retained runtime profile is unsupported.') + bounded_int(runtime['trusted_install_owner_uid'],0,2**32-2,'Runtime owner') + if runtime['assumption'] != TRUST: raise WorkbenchError('Runtime trust policy differs.') + files = runtime['files']; total = 0 + if not isinstance(files,dict) or not 1 <= len(files) <= 10000: raise WorkbenchError('Invalid runtime closure size.') + for path, item in files.items(): + if not isinstance(path,str) or not (path.startswith('/usr/') or path == '/etc/' + Path(runtime['executable']).name + '/sitecustomize.py'): + raise WorkbenchError('Runtime path escapes the supported trusted installation.') + relative_path(path[1:]); closed(item,('bytes','sha256')); sha(item['sha256']) + bounded_int(item['bytes'],0,64*1024*1024,'Runtime file bytes'); total += item['bytes'] + if total > RUNTIME_LIMIT or runtime['executable'] not in files or files[runtime['executable']]['sha256'] != runtime['executable_sha256'] or digest(files) != runtime['closure_sha256']: + raise WorkbenchError('Runtime closure identity is inconsistent.') + if not isinstance(material['host_files'],dict) or set(material['host_files']) != set(HOST_NAMES): raise WorkbenchError('Invalid retained host closure.') + for value in material['host_files'].values(): sha(value) + return material + + +def spec_for_material(material, staging): + """Pure reconstruction: retained approvals never depend on current source/runtime.""" + validate_material(material) + staging = Path(staging).absolute() + output = staging/'output' + definition = material['recipe']; runtime = material['runtime'] + records = [dict(path=str(staging/relative), **record) for relative,record in sorted(material['captures'].items())] + argv = [runtime['executable'], *runtime['flags'], str(staging/'source'/definition['entrypoint'])] + for token in definition['arguments']: + kind, value = next(iter(token.items())) + if kind == 'literal': arg = value + elif kind == 'parameter': + item = material['parameters'][value]; arg = ('true' if item else 'false') if type(item) is bool else str(item) + elif kind == 'input': arg = str(staging/'input'/value) + elif kind == 'source': arg = str(staging/'source'/value) + else: arg = str(output) + argv.append(arg) + return {'schema_version':1,'argv':argv,'env':dict(material['environment']),'cwd':str(staging), 'stdin_base64':base64.b64encode(b'').decode(), + 'wall_seconds':definition['resources']['wall_seconds'], 'executable_sha256':runtime['executable_sha256'], + 'max_output_bytes':definition['resources']['max_output_bytes'], 'output_dir':str(output),'captured_files':records, + 'runtime_files':[dict(path=path,**record) for path,record in sorted(runtime['files'].items())], + 'trusted_install_owner_uid':runtime['trusted_install_owner_uid']} + + +def validate_spec(material, spec, staging): + expected = spec_for_material(material, staging) + actual = {key:value for key,value in spec.items() if key not in ('attempt_id', 'request_sha256')} + if encode(actual) != encode(expected): + raise WorkbenchError('Execution specification differs from the approved material.', 'conflict', 409) + return expected + + +def _sync_directory(path): + fd = os.open(path, os.O_RDONLY|os.O_DIRECTORY|os.O_NOFOLLOW) + try: os.fsync(fd) + finally: os.close(fd) + + +def capture(preflight, captured, staging): + staging = Path(staging).absolute() + # The Runs owner supplies an existing private attempt parent, never a client path. + staging.mkdir(mode=0o700, exist_ok=False) + output = staging/'output'; output.mkdir(mode=0o700) + for relative, raw in captured.items(): + path = staging/relative; path.parent.mkdir(mode=0o700,parents=True,exist_ok=True) + with path.open('xb') as handle: + handle.write(raw); handle.flush(); os.fchmod(handle.fileno(),0o400); os.fsync(handle.fileno()) + for directory, _dirs, _files in os.walk(staging, topdown=False): + _sync_directory(directory) + _sync_directory(staging.parent) + return dict(preflight, spec=spec_for_material(preflight['material'], staging)) + + +def verify_outputs(output_dir, outputs, max_output_bytes): + root = Path(output_dir) + if root.is_symlink() or not root.is_dir(): raise WorkbenchError('Output root is not a regular directory.') + allowed = {entry['path']:entry for entry in outputs}; found = {}; total = 0 + for directory, dirs, files in os.walk(root, followlinks=False): + if any((Path(directory)/name).is_symlink() for name in dirs): raise WorkbenchError('Output directory symlinks are forbidden.') + for name in files: + path = Path(directory)/name; relative = path.relative_to(root).as_posix() + if relative not in allowed or len(found) >= MAX_FILES: raise WorkbenchError('Undeclared output file.') + fd = os.open(path, os.O_RDONLY|os.O_NOFOLLOW|os.O_NONBLOCK) + try: + info = os.fstat(fd); rule = allowed[relative] + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_size > rule['max_bytes']: raise WorkbenchError('Output must be a bounded unlinked regular file.') + chunks = []; remaining = rule['max_bytes']+1 + while remaining: + raw = os.read(fd,min(65536,remaining)) + if not raw: break + chunks.append(raw); remaining -= len(raw) + raw = b''.join(chunks); after = os.fstat(fd) + if len(raw) != info.st_size or (info.st_size,info.st_mtime_ns,info.st_ctime_ns) != (after.st_size,after.st_mtime_ns,after.st_ctime_ns): raise WorkbenchError('Output changed during verification.') + total += len(raw) + if total > max_output_bytes: raise WorkbenchError('Output total exceeds declared limit.') + found[relative] = {'path':relative,'role':rule['role'],'bytes':len(raw),'sha256':file_digest(raw)} + finally: os.close(fd) + if any(item['required'] and item['path'] not in found for item in outputs): raise WorkbenchError('Required output is missing.') + return list(found.values()) diff --git a/recipe_process.py b/recipe_process.py new file mode 100644 index 00000000..0adc669b --- /dev/null +++ b/recipe_process.py @@ -0,0 +1,491 @@ +"""Linux per-attempt child custody. Runs owns admission, scheduling and publication. + +Trusted reviewed recipes share the local UID. Subreaping is lifecycle ownership, +not filesystem/network confinement. A missing drain receipt never proves cessation. +""" +import base64 +import ctypes +import fcntl +import hashlib +import json +import os +from pathlib import Path +import re +import resource +import selectors +import signal +import socket +import stat +import subprocess +import time + +READY_SECONDS = 10 +GRACE_SECONDS = 3 +CLEANUP_SECONDS = 10 +STREAM_LIMIT = 1024 * 1024 +OUTPUT_LIMIT = 64 * 1024 * 1024 +SPEC_LIMIT = 4 * 1024 * 1024 +SOURCE = Path(__file__).read_bytes() +HASH = re.compile(r'^[a-f0-9]{64}$') +ID = re.compile(r'^[a-f0-9]{32}$') +# Linux UAPI values: some supported Python builds omit the symbolic constants. +F_ADD_SEALS = getattr(fcntl, 'F_ADD_SEALS', 1033) +IMMUTABLE_SEALS = 0x0001 | 0x0002 | 0x0004 | 0x0008 + + +class ProcessError(ValueError): + def __init__(self, message, code='invalid'): + super().__init__(message) + self.code = code + + +def encoded(value): + return json.dumps(value, sort_keys=True, separators=(',', ':'), allow_nan=False).encode() + + +def digest(raw): + return hashlib.sha256(raw).hexdigest() + + +def decode(raw): + def pairs(items): + result = {} + for key, value in items: + if key in result: + raise ValueError('duplicate key') + result[key] = value + return result + try: + return json.loads(raw, object_pairs_hook=pairs, parse_constant=lambda _: (_ for _ in ()).throw(ValueError())) + except (ValueError, UnicodeError, RecursionError) as error: + raise ProcessError('Invalid custody JSON.') from error + + +def text(value, maximum=4096): + return type(value) is str and 0 < len(value) <= maximum and not any(ord(c) < 32 or 0xD800 <= ord(c) <= 0xDFFF for c in value) + + +def absolute(value): + return text(value) and Path(value).is_absolute() and '..' not in Path(value).parts + + +def validate_spec(value): + keys = {'schema_version','attempt_id','request_sha256','argv','env','cwd','stdin_base64', + 'wall_seconds','executable_sha256','max_output_bytes','output_dir','captured_files','runtime_files','trusted_install_owner_uid'} + if type(value) is not dict or set(value) != keys or type(value['schema_version']) is not int or value['schema_version'] != 1: + raise ProcessError('Unsupported custody spec.') + if not isinstance(value['attempt_id'], str) or not ID.fullmatch(value['attempt_id']): + raise ProcessError('Invalid attempt identity.') + for key in ('request_sha256','executable_sha256'): + if type(value[key]) is not str or not HASH.fullmatch(value[key]): + raise ProcessError('Invalid custody hash.') + argv, env = value['argv'], value['env'] + if type(argv) is not list or not 1 <= len(argv) <= 64 or not all(text(arg) for arg in argv) or not absolute(argv[0]): + raise ProcessError('Invalid captured argument vector.') + if type(env) is not dict or len(env) > 32 or any(not re.fullmatch('[A-Z_][A-Z0-9_]{0,63}', key) or type(val) is not str or len(val) > 4096 or '\0' in val for key,val in env.items()): + raise ProcessError('Invalid explicit environment.') + if not absolute(value['cwd']) or not absolute(value['output_dir']): + raise ProcessError('Captured working/output directories must be absolute.') + if type(value['wall_seconds']) is not int or not 1 <= value['wall_seconds'] <= 600: + raise ProcessError('Wall budget must be 1 through 600 seconds.') + if type(value['max_output_bytes']) is not int or not 1 <= value['max_output_bytes'] <= OUTPUT_LIMIT: + raise ProcessError('Invalid output byte budget.') + try: + if type(value['stdin_base64']) is not str or len(value['stdin_base64']) > 87384: + raise ValueError() + if len(base64.b64decode(value['stdin_base64'], validate=True)) > 65536: + raise ValueError() + except ValueError as error: + raise ProcessError('Stdin exceeds its 64 KiB bound or is invalid base64.') from error + if type(value['trusted_install_owner_uid']) is not int or value['trusted_install_owner_uid'] == os.getuid() or value['trusted_install_owner_uid'] < 0: + raise ProcessError('Runtime owner must be an explicitly distinct trusted installation identity.') + runtime = value['runtime_files'] + if type(runtime) is not list or len(runtime)>10000: + raise ProcessError('Invalid runtime inventory.') + files = value['captured_files'] + if type(files) is not list or len(files) > 128: + raise ProcessError('Invalid captured file inventory.') + seen = set() + for item in files+runtime: + if type(item) is not dict or set(item) != {'path','sha256','bytes'} or not absolute(item['path']): + raise ProcessError('Invalid captured file reference.') + if item['path'] in seen or type(item['sha256']) is not str or not HASH.fullmatch(item['sha256']): + raise ProcessError('Duplicate capture or invalid hash.') + seen.add(item['path']) + if type(item['bytes']) is not int or not 0 <= item['bytes'] <= OUTPUT_LIMIT: + raise ProcessError('Invalid captured file size.') + if sum(item['bytes'] for item in files)>64*1024*1024 or sum(item['bytes'] for item in runtime)>512*1024*1024: + raise ProcessError('Runtime/source closure exceeds its byte bound.') + if len(encoded(value)) > SPEC_LIMIT: + raise ProcessError('Custody specification exceeds its bound.') + return decode(encoded(value)) + + +def read_regular(path, maximum): + descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) + with os.fdopen(descriptor, 'rb') as handle: + before = os.fstat(handle.fileno()) + if not stat.S_ISREG(before.st_mode) or before.st_size > maximum: + raise ProcessError('Expected a bounded regular captured file.', 'unavailable') + raw = handle.read(maximum + 1) + after = os.fstat(handle.fileno()) + if len(raw) > maximum or (before.st_size,before.st_mtime_ns,before.st_ctime_ns) != (after.st_size,after.st_mtime_ns,after.st_ctime_ns): + raise ProcessError('Captured file changed during observation.', 'stale') + return raw + + +def verify_captures(spec): + for item in spec['captured_files']+spec['runtime_files']: + raw = read_regular(item['path'], item['bytes']) + if len(raw) != item['bytes'] or digest(raw) != item['sha256']: + raise ProcessError('Captured input/source identity changed.', 'stale') + + +def identity(pid): + fields = Path(f'/proc/{pid}/stat').read_text().rsplit(')',1)[1].split() + return {'pid':pid, 'start_ticks':fields[19], 'boot_id':Path('/proc/sys/kernel/random/boot_id').read_text().strip()} + + +def valid_identity(value): + return (type(value) is dict and set(value)=={'pid','start_ticks','boot_id'} and + type(value['pid']) is int and value['pid']>0 and type(value['start_ticks']) is str and value['start_ticks'].isdigit() and + type(value['boot_id']) is str and re.fullmatch('[a-f0-9-]{36}',value['boot_id']) is not None) + + +def sealed(name, raw): + fd = os.memfd_create(name, os.MFD_ALLOW_SEALING) + try: + with os.fdopen(os.dup(fd), 'wb') as handle: + handle.write(raw); handle.flush() + os.lseek(fd, 0, os.SEEK_SET) + fcntl.fcntl(fd, F_ADD_SEALS, IMMUTABLE_SEALS) + return fd + except BaseException: + os.close(fd) + raise + + +def _trusted_python(owner_uid): + path = Path('/usr/bin/python3').resolve(strict=True) + if '/usr' not in str(path) or not str(path).startswith('/usr/'): + raise ProcessError('Trusted system Python is unavailable.', 'unavailable') + for item in (path,*path.parents): + info = item.stat() + if info.st_uid != owner_uid or info.st_mode & 0o022 or os.access(item,os.W_OK): + raise ProcessError('System Python installation is writable.', 'unavailable') + return str(path) + + +def _packet(channel, value): + raw = encoded(value) + if len(raw) > 4096: + raise ProcessError('Custodian message exceeds its bound.') + channel.send(raw) + + +def _receive(channel): + raw, _ancillary, flags, _address = channel.recvmsg(4096) + if not raw: + return None + if flags & socket.MSG_TRUNC: + raise ProcessError('Truncated custodian message.') + return decode(raw) + + +class Handle: + def __init__(self, process, channel, spec, directory): + self.process, self.channel, self.spec, self.directory = process, channel, spec, directory + self.ready = None + self.sent_go = self.terminal = self.lost = self.sent_cancel = False + self.started = time.monotonic() + self.spec_sha256 = digest(encoded(spec)) + + @property + def expected_identity(self): + return {'attempt_id':self.spec['attempt_id'],'request_sha256':self.spec['request_sha256'], + 'spec_sha256':self.spec_sha256,'helper':self.ready} + + def poll(self): + events = [] + if self.channel is None: + if not self.terminal and not self.lost: + self.lost = True + events.append({'type':'lost','reason':'custodian_channel_closed'}) + return events + while True: + try: + event = _receive(self.channel) + except BlockingIOError: + break + except (OSError, ProcessError): + event = None + if event is None: + if not self.terminal and not self.lost: + self.lost = True + events.append({'type':'lost','reason':'custodian_channel_closed'}) + self.close_control(wait=False) + break + common = {'schema_version':1,'attempt_id':self.spec['attempt_id'],'request_sha256':self.spec['request_sha256'],'spec_sha256':self.spec_sha256} + kind = event.get('type') if type(event) is dict else None + fields = {'ready':{'helper'},'started':{'leader'},'terminal':{'receipt_sha256','drained','outcome'}} + if kind not in fields or set(event) != set(common)|{'type'}|fields[kind] or any(event[key] != val for key,val in common.items()): + self.cancel('protocol_error'); raise ProcessError('Invalid custodian event.') + if kind == 'ready': + if self.ready is not None or not valid_identity(event['helper']) or event['helper'] != identity(self.process.pid): + self.cancel('protocol_error'); raise ProcessError('Invalid custodian READY identity.') + self.ready = event['helper'] + elif kind == 'started': + if not self.sent_go or not valid_identity(event['leader']): + self.cancel('protocol_error'); raise ProcessError('Invalid recipe STARTED identity.') + else: + receipt = load_receipt(self.directory/'receipt.json', self.expected_identity) + if digest(encoded(receipt)) != event['receipt_sha256'] or receipt['drained'] != event['drained'] or receipt['outcome'] != event['outcome']: + raise ProcessError('Terminal receipt differs from custodian event.') + self.terminal = True + events.append(event) + if self.ready is None and not self.lost and time.monotonic()-self.started > READY_SECONDS: + self.close_control(wait=False) + raise ProcessError('Custodian readiness deadline exceeded.', 'unavailable') + self.process.poll() + return events + + def go(self, expected_ready_identity): + if self.ready is None or expected_ready_identity != self.ready or self.sent_go or self.terminal or self.channel is None: + raise ProcessError('GO requires the exact READY identity once.') + _packet(self.channel, {'type':'go','attempt_id':self.spec['attempt_id'],'request_sha256':self.spec['request_sha256'],'helper':self.ready}) + self.sent_go = True + + def cancel(self, reason='cancelled'): + if reason not in ('cancelled','shutdown','protocol_error'): + raise ProcessError('Unsupported cancellation reason.') + if self.channel is not None and not self.sent_cancel: + self.sent_cancel = True + try: _packet(self.channel, {'type':'cancel','reason':reason}) + except (OSError, ProcessError): self.close_control(wait=False) + + def close_control(self, *, wait=True): + if self.channel is not None: + self.channel.close(); self.channel = None + if not wait: + return None + try: + self.process.wait(timeout=CLEANUP_SECONDS + 2) + except subprocess.TimeoutExpired as error: + raise ProcessError('Custodian did not finish drainage within its cleanup budget.', 'unknown') from error + if self.ready is None: + return {'drained':False,'outcome':'unknown','reason':'no_ready_identity'} + try: + return load_receipt(self.directory/'receipt.json',self.expected_identity) + except (OSError,ProcessError): + return {'drained':False,'outcome':'unknown','reason':'missing_drain_receipt'} + + +def launch(spec, custody_dir): + spec = validate_spec(spec) + verify_captures(spec) + executable = read_regular(spec['argv'][0], 128*1024*1024) + if digest(executable) != spec['executable_sha256']: + raise ProcessError('Executable identity changed.', 'stale') + directory = Path(custody_dir) + directory.mkdir(mode=0o700, parents=False, exist_ok=False) + parent = child = None + descriptors = [] + try: + parent, child = socket.socketpair(socket.AF_UNIX, socket.SOCK_SEQPACKET) + for name, raw in (('tuldok-custodian',SOURCE),('tuldok-spec',encoded(spec)),('tuldok-executable',executable)): + descriptors.append(sealed(name,raw)) + directory_fd = os.open(directory, os.O_RDONLY|os.O_DIRECTORY|os.O_NOFOLLOW) + descriptors.append(directory_fd) + command = [_trusted_python(spec['trusted_install_owner_uid']),'-I','-B',f'/proc/self/fd/{descriptors[0]}','--helper',str(child.fileno()),*(str(fd) for fd in descriptors[1:])] + process = subprocess.Popen(command, stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL, + pass_fds=(child.fileno(),*descriptors),close_fds=True,env={'PATH':'/usr/bin:/bin','LANG':'C.UTF-8'}) + parent.setblocking(False) + return Handle(process,parent,spec,directory) + except BaseException: + if parent is not None: parent.close() + raise + finally: + if child is not None: child.close() + for fd in descriptors: os.close(fd) + + +def load_receipt(path, expected_identity): + if type(expected_identity) is not dict or set(expected_identity) != {'attempt_id','request_sha256','spec_sha256','helper'} or not valid_identity(expected_identity['helper']): + raise ProcessError('An exact READY identity is required to read a receipt.') + raw = read_regular(path,16384) + value = decode(raw) + fields = {'schema_version','attempt_id','request_sha256','spec_sha256','helper','go_received','spawn_closed', + 'drained','echild','outcome','reason','leader_returncode','streams'} + if type(value) is not dict or set(value)!=fields or type(value['schema_version']) is not int or value['schema_version']!=1 or any(value.get(k)!=v for k,v in expected_identity.items()): + raise ProcessError('Invalid retained custody receipt.') + if not valid_identity(value['helper']) or any(type(value[k]) is not bool for k in ('go_received','spawn_closed','drained','echild')): + raise ProcessError('Invalid receipt custody evidence.') + if not value['spawn_closed'] or value['drained'] != value['echild'] or value['outcome'] not in ('completed','failed','cancelled','unknown'): + raise ProcessError('Receipt cannot establish its claimed drainage.') + if not value['drained'] and value['outcome']!='unknown': + raise ProcessError('Unconfirmed drainage must remain unknown.') + if value['leader_returncode'] is not None and type(value['leader_returncode']) is not int: + raise ProcessError('Invalid leader exit status.') + if value['outcome']=='completed' and (not value['go_received'] or value['leader_returncode']!=0): + raise ProcessError('Completion requires successful execution.') + if not text(value['reason'],100) or type(value['streams']) is not dict or set(value['streams'])!={'stdout','stderr'}: + raise ProcessError('Invalid retained diagnostics.') + for row in value['streams'].values(): + if type(row) is not dict or set(row)!={'bytes','sha256'} or type(row['bytes']) is not int or not 0<=row['bytes']<=STREAM_LIMIT or type(row['sha256']) is not str or not HASH.fullmatch(row['sha256']): + raise ProcessError('Invalid stream receipt.') + return value + + +def _children(): + # /proc/.../children is not exposed on every supported host. PPID is the + # admitted canonical observation; ECHILD, never this scan, proves drainage. + result = [] + for path in Path('/proc').iterdir(): + if not path.name.isdigit(): + continue + try: + fields = (path/'stat').read_text().rsplit(')',1)[1].split() + if int(fields[1]) == os.getpid(): + result.append(int(path.name)) + except FileNotFoundError: + continue + if len(result)>4096: + raise ProcessError('Child inventory exceeds custody bound.', 'unknown') + return result + + +def _signal_children(number): + for pid in _children(): + try: + fd = os.pidfd_open(pid) + try: signal.pidfd_send_signal(fd,number) + finally: os.close(fd) + except ProcessLookupError: + pass + + +def _outputs(spec): + root=Path(spec['output_dir']); total=count=0 + if root.is_symlink() or not root.is_dir(): + raise ProcessError('Output directory changed.') + for path in root.iterdir(): + info=path.lstat();count+=1;total+=info.st_size + if count>128 or not stat.S_ISREG(info.st_mode) or total>spec['max_output_bytes']: + raise ProcessError('Output inventory exceeded its admitted bound.') + + +def _helper(control_fd,spec_fd,exe_fd,directory_fd): + channel=socket.socket(fileno=control_fd);channel.setblocking(False) + spec=validate_spec(decode(os.pread(spec_fd,SPEC_LIMIT+1,0))) + libc=ctypes.CDLL(None,use_errno=True) + if libc.prctl(36,1,0,0,0): raise OSError(ctypes.get_errno(),'subreaper unavailable') + who=identity(os.getpid());common={'schema_version':1,'attempt_id':spec['attempt_id'],'request_sha256':spec['request_sha256'],'spec_sha256':digest(encoded(spec))} + logs={};hashes={name:hashlib.sha256() for name in ('stdout','stderr')};sizes={name:0 for name in hashes} + for name in hashes: logs[name]=os.open(name+'.log',os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600,dir_fd=directory_fd) + selector=selectors.DefaultSelector();selector.register(channel,selectors.EVENT_READ,'control') + leader=None;code=None;go=False;stopping=None;reason='not_started';drained=False + started=time.monotonic();deadline=started+READY_SECONDS + def stop(why): + nonlocal stopping,reason + if stopping is None: stopping=time.monotonic();reason=why + try: + verify_captures(spec) + _packet(channel,dict(common,type='ready',helper=who)) + while True: + now=time.monotonic() + if stopping is None and now>=deadline:stop('wall_timeout' if go else 'ready_timeout') + if go and stopping is None: + try:_outputs(spec) + except (OSError,ProcessError):stop('output_limit') + if stopping is not None: + try:_signal_children(signal.SIGKILL if now-stopping>=GRACE_SECONDS else signal.SIGTERM) + except (OSError,ProcessError):reason='child_observation_failed';break + for _ in range(256): + try: + pid,status=os.waitpid(-1,os.WNOHANG) + except ChildProcessError: + if stopping is not None or go:drained=True + break + if pid==0:break + if pid==leader:code=os.waitstatus_to_exitcode(status) + if go and code is not None and stopping is None:stop('exited' if code==0 else 'nonzero_exit') + streams_open=any(key.data!='control' for key in selector.get_map().values()) + if drained and not streams_open:break + if stopping is not None and now-stopping>=CLEANUP_SECONDS: + if streams_open:drained=False;reason='stream_cessation_unknown' + break + for key,_mask in selector.select(.05): + if key.data=='control': + try:message=_receive(channel) + except (OSError,ProcessError):message=None + if message is None: + selector.unregister(channel);stop('controller_lost');continue + if type(message) is dict and set(message)=={'type','reason'} and message['type']=='cancel' and message['reason'] in ('cancelled','shutdown','protocol_error'): + stop(message['reason']);continue + expected={'type':'go','attempt_id':spec['attempt_id'],'request_sha256':spec['request_sha256'],'helper':who} + if message!=expected or go or stopping is not None:stop('protocol_error');continue + verify_captures(spec) + go=True;deadline=time.monotonic()+spec['wall_seconds'] + input_fd=sealed('tuldok-stdin',base64.b64decode(spec['stdin_base64'])) + pipes={name:os.pipe() for name in hashes} + leader=os.fork() + if leader==0: + try: + os.setsid();os.chdir(spec['cwd']) + os.dup2(input_fd,0);os.dup2(pipes['stdout'][1],1);os.dup2(pipes['stderr'][1],2) + for entry in os.listdir('/proc/self/fd'): + fd=int(entry) + if fd>2 and fd!=exe_fd: + try:os.close(fd) + except OSError:pass + resource.setrlimit(resource.RLIMIT_FSIZE,(spec['max_output_bytes'],spec['max_output_bytes'])) + os.execve(exe_fd,spec['argv'],spec['env']) + except BaseException:os._exit(126) + os.close(input_fd) + for name,(read_fd,write_fd) in pipes.items(): + os.close(write_fd);os.set_blocking(read_fd,False);selector.register(read_fd,selectors.EVENT_READ,name) + _packet(channel,dict(common,type='started',leader=identity(leader))) + else: + data=os.read(key.fd,65536) + if not data:selector.unregister(key.fd);os.close(key.fd);continue + name=key.data;kept=data[:max(0,STREAM_LIMIT-sizes[name])] + pending=memoryview(kept) + while pending: + written=os.write(logs[name],pending) + if not written:raise OSError('Diagnostic write made no progress') + pending=pending[written:] + hashes[name].update(kept);sizes[name]+=len(kept) + if len(kept)!=len(data):stop('stream_limit') + except BaseException: + stop('custodian_error') + deadline=time.monotonic()+CLEANUP_SECONDS + while time.monotonic()