Reviewed release API and storage

The gateway retains exact file or mapped SQL snapshots under an explicit deployment policy. It does not write sources or transfer data authority. OSDU retention and sharing are not qualified. Both capture and approval require can_administer; self-approval is identified. A project member in the release audience may inspect.

Configure each connection’s release_policy with strict boolean retention_permitted, redistribution_permitted, and an audience array of account IDs. Both permissions must be true to capture. Default is deny; legacy snapshots_permitted is ignored. Restart after changing the registry. Effective access is frozen audience intersect current policy audience intersect current project members; current retention/redistribution must remain enabled. Source read principals are checked only for acquisition. Readers of retained copies never borrow the creator’s upstream credential. Removing project or distribution access denies subsequent reads, including for the creator. Exports cannot be recalled.

Lifecycle and API

Browser POST /api/releases/{operation} uses existing session, Origin and CSRF. Automation POST /api/v1/projects/{project}/releases/{operation} uses project-scoped Bearer credentials and current parent/project authorization. capture, approve and withdraw require write scope plus administrator rights; list, get, preview, compare, download and options require read scope. Options additionally requires administration because it exposes eligible account-owned selections. Unknown operations return 404. Desktop connector sessions expose no release routes.

All requests contain project_id. Capture adds command_id, name, purpose, selection_ids (1–10), audience (including creator) and optional previous_id. The same command/body returns the original candidate; different body returns 409. Get takes id. Approve takes id, manifest_digest, exact purpose, and every acknowledged_findings ID. Same actor and tuple retries return the receipt without a new event. Withdraw takes id, manifest_digest and nonempty reason. Withdrawal is terminal, blocks downloads/reapproval and preserves inspectable metadata for authorized readers. It does not delete or recall copies. There is no purge API in this pilot. Unauthorized and nonexistent packages return the same 404; wrong mutation role is 403; stale/conflicting decisions and corruption are 409.

Immutable manifest schema ophiolite.reviewed-release/1 includes exact source manifests, original authority, interpretation, mapping/schema/profile versions, policy digest, audience, purpose, content-derived finding IDs and creator/time. Digest is SHA-256 of JSON encoded as UTF-8 with sort_keys=True, separators=(',',':'), allow_nan=False, ensure_ascii=True, without a self-digest field. Approval records actor, time, digest, purpose, finding IDs and self-approval. Human approval does not resolve an unknown datum or certify scientific fidelity.

Durability and limits

One gateway process only. Read/hash outside the in-process lock; capture writes manifest, BLOB payloads, command identity and event in one SQLite transaction. The bounded fsync can block other journal activity briefly. Limits: 10 assets, 16 MiB/file, 64 MiB/package, 512 MiB retained deployment total, 100 candidates/project. Underlying limits remain: SQL 1,000 rows/4 MiB; GeoTIFF single band/1M cells; LAS 2.0 UTF-8. SQL revisions pin schema, rows and mapping; mapped ID determines identity. Names never merge entities. Rollback journal can need roughly twice package size transiently. Capacity refusal requires administrator action; no silent deletion. Missing exact history refuses capture. Retained bytes survive subsequent upstream replacement and deletion.

Journal.backup(new_path) uses SQLite backup under its lock; destination must not exist and is created 0600. Restore with gateway stopped, replacing its journal with the backup, then restart. Registry and identity/project database require their own backups. Existing edit-results/ draft artifacts are outside this journal backup.

Data, comparison and independent exit

Preview takes id and zero-based asset. It returns at most 200 table rows, total_rows and truncated; missing values are JSON null, empty text is "". Original LAS retains its declared NULL marker. No fill, interpolation, CRS or unit conversion occurs. Preview parsing reuses the qualified typed Connector reader. GeoTIFF returns retained metadata, not a semantic difference image.

Compare takes id and previous_id; both packages require authorization. Identity is authority plus logical key. The response records added/removed/changed assets, exact byte/context changes and at most 1,000 mapped cell differences, including field-presence flags and null transitions. LAS comparisons align source row positions, not inferred geological features. SQL comparisons align mapped row IDs. Original SQL columns beyond the mapped view remain in exported source_rows; byte changes can exist with no mapped cell differences. Raster comparison is byte/context only. Comparison never changes or merges data.

Download returns filename and base64 ZIP for an approved active release. Fixed entry names/order/timestamps make repeated downloads identical. manifest.json and receipt.json accompany assets/00.las, .tif or .json by source profile. Receipt contains the approval record, not private credentials. Verify SHA-256 against exact original bytes and recompute the canonical manifest digest. This is integrity evidence, not a digital signature. Integration’s standalone tools/verify_release_bundle.py needs only standard Python. Release requests are limited to two concurrent calls per gateway; excess requests return 409 to retry.

Optional review extension

See collection and snapshot contracts for unreviewed capture, request-review, new receipt schema and automation scopes. Legacy capture defaults and approved download gates remain unchanged.