trevor — Domain Glossary¶

Canonical definitions for all terms used in the trevor codebase, specs, and documentation. When in doubt, use these terms exactly.

Core entities¶

Airlock Request The top-level unit of work in trevor. A researcher initiates an airlock request to move one or more output objects across the TRE security boundary. A request has a direction (ingress or egress), a status, a project association, and an ordered list of output objects. A single request covers a coherent body of work (e.g. "outputs for paper X").

Output Object A single file submitted as part of an airlock request. An output object has a type (see Output Type), metadata, a checksum, and a version lineage. Output objects are immutable once submitted. A replacement object is a new output object linked to a previous one via the replaces field.

Output Type The category of an output object, used to determine which statbarn rules apply and how the object should be rendered in the UI. Valid types: table_markdown, table_csv, table_parquet, plot_image, model_output, narrative_markdown, document_pdf, code, other.

Statbarn A classification category from the SACRO output checking framework that groups statistics by their shared disclosure risk profile and SDC rules. Each output object is assigned a statbarn by the researcher and reviewed by the agent and human checkers. See outputchecking.org/operations/ for the canonical list.

Review A recorded decision made by a checker (human or agent) on an airlock request. A review has a decision (approved, rejected, changes_requested), a reviewer identity, a timestamp, and structured feedback per output object.

Reviewer / Output Checker A user with the output_checker or senior_checker role who is assigned to a project and authorised to review airlock requests for that project.

Senior Checker A reviewer with elevated authority. Can override agent and standard checker decisions. Required for escalations and policy exceptions. See ADR-0010.

Agent Review An automated review performed by the trevor autonomous agent immediately on request submission. Produces a structured report assessing each output object against statbarn rules. This is advisory; it does not block human review. Counts as one of the two required reviews if the human checker accepts the agent's findings.

RO-Crate A Research Object Crate (RO-Crate 1.1) package generated at the point of final approval for egress requests. Contains all approved output objects plus their metadata, provenance, and the approval record. This is what gets placed in external storage for download.

Quarantine Storage The internal S3-compatible bucket that holds all uploaded files while they are under review. Accessible only to trevor. Researchers and checkers interact with files through trevor's UI; they never have direct bucket credentials.

Release Storage The external-facing S3-compatible bucket that holds approved RO-Crate packages. Access is granted exclusively via pre-signed, time-limited URLs generated by trevor at the point of release.

Pre-signed URL A time-limited, cryptographically signed URL that grants temporary read access to a specific object in Release Storage. Generated by trevor at release time. Delivered to the designated recipient(s) via the notification system.

Roles¶

Researcher A TRE workspace member who submits airlock requests. Cannot review requests for any project they are a member of. May be a checker on unrelated projects.

Output Checker (output_checker) A user authorised to review and provide feedback on airlock requests for assigned projects. Their approval counts as one review. May not approve without a second reviewer.

Senior Checker (senior_checker) An output checker with escalation authority. Can make final decisions on contested or flagged requests. Supervises output checkers. Can be the second reviewer.

TRE Administrator (tre_admin) Platform-level admin. Can assign checkers to projects, manage configuration, view all audit logs, and override stuck workflows. Cannot approve requests (separation of duties).

Agent (agent:trevor-agent) The autonomous review agent. Treated as a first reviewer. Its reports are advisory. A human reviewer must always be one of the two required reviewers.

Lifecycle states¶

Airlock Request states¶

DRAFT → SUBMITTED → AGENT_REVIEW → HUMAN_REVIEW → CHANGES_REQUESTED
                                                 → APPROVED → RELEASING → RELEASED
                                                 → REJECTED

Output Object states¶

Metadata concepts¶

Object Metadata Structured annotations attached to an output object. Includes: title, description, statbarn classification, researcher justification, suppression notes, and any checker feedback. Metadata belongs to the logical output object (the lineage chain), not to a specific version.

Lineage Chain The ordered list of object versions for a single logical output. Version 1 is the original submission. Version N supersedes version N-1 via the replaces pointer. Metadata accumulates across versions; the latest version's record holds the full history.

Checksum SHA-256 hash of the file content, computed by trevor at upload time and verified at each state transition. Stored in both the database and the RO-Crate metadata.

Integration concepts¶

CRD (Custom Resource Definition) Kubernetes resource type used by CR8TOR to define TRE projects and workspaces. trevor reads these via the Kubernetes API to discover project memberships and configurations.

CR8TOR The karectl tool responsible for provisioning and managing TRE workspace CRDs. trevor does not write to CR8TOR-managed CRDs.

Karectl The TRE platform that trevor runs within. Provides Kubernetes infrastructure, Keycloak identity, and shared services.