Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Public protocol API

ahri_tre_protocol owns the versioned JSON request and response envelopes used by CLI, daemon, Trusted runtime, C ABI, and language bindings.

Every request carries a protocol version, request identifier, kind, and typed body. Every response is either a typed success payload or a stable safe error. Unknown or removed operations fail explicitly.

Open the generated ahri_tre_protocol Rust API documentation.

The public contract includes:

  • runtime/session status and configured profile selection;
  • Datastore health and safe binding identity;
  • domain, Study, governance, asset, datafile, dataset, variable, vocabulary, tag, entity, relation, transformation, and ingest workflows;
  • operation receipts, pagination, warnings, and safe provenance;
  • optional Arrow IPC payload descriptors for tabular results.

It excludes Secret material, credential names or paths, inline credentials, connection strings, raw SQL authority, Restricted local references, and live handles. Logical Secret references and exact resolved versions may appear only where safe provenance requires them.

The CLI exposes the implemented JSON schemas with schema list and schema get <schema-id>. The registry includes cli.schema.coverage-map.v1 for the current command-to-contract coverage map. Client bootstrap and Application documents have their own versioned configuration schemas.

The current registry identifiers are:

  • cli.schema.coverage-map.v1
  • protocol.request-envelope.v2
  • protocol.response-envelope.v2
  • protocol.success-envelope.v2
  • protocol.failure-envelope.v2
  • protocol.error.v2
  • protocol.warning.v2
  • protocol.mutation.v2
  • protocol.pagination.v2
  • protocol.refs.v2
  • protocol.operation.v2
  • protocol.tabular-ref.v2
  • protocol.session.lifecycle.v2
  • protocol.session.current-study.v2
  • protocol.datastore.lifecycle.v2
  • protocol.datastore.schema-status.v2
  • protocol.daemon.readiness.v2
  • protocol.domain.metadata.v2
  • protocol.study.metadata.v2
  • protocol.study.governance.v2
  • protocol.asset.catalog.v2
  • protocol.datafile.catalog.v2
  • protocol.dataset.catalog.v2
  • protocol.lifecycle.delete.v2
  • protocol.ingest.workflow.v2
  • protocol.transformation.audit.v2
  • protocol.workflow.summary.v2
  • protocol.dictionary.catalog.v2
  • protocol.tag.registry.v2
  • protocol.semantic-model.catalog.v2
  • cli.daemon.lifecycle.v1
  • cli.diagnostics.output.v1
  • cli.version.output.v1
  • cli.doctor.output.v1

Materialization acceptance

ingest.dataset.from_datafile returns a pending StartResult::Operation after atomic persistence of the operation, private attempt, and shared Dataset reservation. It pins the concrete source before acceptance. Poll operation.get or operation.result.get with the selected live Session; polling remains available while Lake work blocks. Results are operation_not_ready until terminalization. Worker saturation returns rate_limited without accepting work; Dataset contention returns a safe conflict with no other owner’s identifiers. An absent executor configuration returns unsupported_operation. The protocol request does not carry a wait flag: --no-wait is a CLI presentation choice.

Materialization cancellation

operation.cancel takes { "session": { "name": "analysis" }, "operation": { "id": "..." } } and returns OperationSummary. Every request rechecks the owner and required resource access. The ID is never an access capability. Cancellation remains responsive through an independent metadata capability.

cancellable reflects the current window. Pending and running work can accept cancel_requested; retries return that summary without another cancellation event. A blocking adapter call may finish before the next checkpoint. Cleanup and safe executor exclusion precede cancelled and output-reservation release. Cleanup failure returns a terminal safe cleanup_failed classification and retains private evidence and ownership. Terminal status alone cannot make the Dataset reusable.

Entering final admission atomically closes cancellation and publishes the committing stage. Cancellation then returns conflict. A request accepted after the last cooperative checkpoint may still finish completed or failed; the authoritative Dataset admission outcome wins. Completed, failed, and cancelled operations reject cancellation. A policy without cancellation support returns unsupported_operation. Configured runtimes advertise all four operation request kinds.

Operation retention and results

Terminal summaries, events and typed receipts expire exactly 30 days after finished_at; active work has no deadline. Get, event and result reads return not-found at operation expiry, and history omits expired rows before pagination and cursor lookahead, even when physical cleanup is delayed. Completed status is preserved if its result expires early, is removed, or becomes unavailable. The summary’s result reference and operation_result_unavailable detail distinguish expired, removed and unavailable; current source and output authority still apply. Successful result receipts include retention and availability alongside kind and data. Status and result text output display these protocol fields.

Idempotency protection lasts while active and until both acceptance plus 24 hours and the terminal operation deadline have passed. If public history expires inside that minimum key window, a retry returns not-found without executing new work. Expired keys may be reused only after the normal output-reservation checks. Startup and explicit Session opening perform bounded metadata housekeeping, at most 100 expired operations per pass. Housekeeping never releases reservations or deletes private cleanup evidence, Datafiles, Dataset versions, Transformation provenance or audit records. No public prune command or retention setting exists.