Receipt and event schemas - CTRLRun

A receipt is one executed action; an event is one step on the way. Both are written to the store, appended to .ctrlrun/receipts.jsonl and .ctrlrun/events.jsonl as one JSON object per line, and exported to any sink installed. Every enum renders by value, so a reader that never imported CTRLRun can read the evidence.

Receipt

ctrlrun.receipt/v3. seq, prev_hash and hash are the chain; policy_hash and policy_version say which policy decided the action; controls are the registry ids the action and its matched rule cite.

Field	Type	Default
`receipt_id`	`str`	required
`action_id`	`str`	required
`action`	`str`	required
`action_hash`	`str`	required
`principal`	`Principal`	required
`resource`	`str	None`	required
`arguments`	`Mapping`	required
`environment`	`str`	required
`decision`	`Decision`	required
`decision_reason`	`str`	required
`result`	`ReceiptResult`	required
`started_at`	`datetime`	required
`finished_at`	`datetime`	required
`approval_id`	`str	None`	`None`
`approver`	`str	None`	`None`
`effect_key`	`str	None`	`None`
`attempt`	`int`	`1`
`error`	`str	None`	`None`
`execution`	`ctrlrun.receipt.ReceiptResult	None`	`None`
`would_have`	`ctrlrun.receipt._WouldHave	None`	`None`
`seq`	`int	None`	`None`
`prev_hash`	`str	None`	`None`
`policy_hash`	`str	None`	`None`
`policy_version`	`str	None`	`None`
`controls`	`tuple`	`()`
`hash`	`str	None`	`None`

Result

Value	Meaning
`committed`	the executor returned; the remote did it
`failed`	the executor raised `NotExecuted`; the remote provably did nothing
`ambiguous`	the executor raised anything else, timed out, or never returned; nobody knows
`denied`
`blocked`	refused before the executor ran: denied, mismatched approval, duplicate or ambiguous effect
`observed`	observe mode: executed, with what enforce mode would have done recorded in `would_have`

Event

Field	Type	Default
`type`	`EventType`	required
`action_id`	`str	None`	required
`ts`	`datetime`	required
`data`	`Mapping`	`(empty)`
`effect_key`	`str	None`	`None`
`approval_id`	`str	None`	`None`
`event_id`	`int	None`	`None`

Event types

In the order the specification introduced them. The five authority types appear only in a configuration with an authority: section.

Type
`ACTION_PROPOSED`
`POLICY_EVALUATED`
`APPROVAL_REQUESTED`
`APPROVAL_GRANTED`
`APPROVAL_DENIED`
`APPROVAL_EXPIRED`
`APPROVAL_INVALIDATED`
`APPROVAL_CONSUMED`
`EFFECT_RESERVED`
`EFFECT_RESERVATION_REFUSED`
`EXECUTION_STARTED`
`EXECUTION_COMMITTED`
`EXECUTION_FAILED`
`EXECUTION_AMBIGUOUS`
`EFFECT_RESOLVED`
`ACTION_DENIED`
`RECONCILIATION_STARTED`
`RECONCILIATION_RESOLVED`
`EXECUTION_SUSPENDED`
`EXECUTION_RESUMED`
`AUTHORITY_RESOLVED`
`AUTHORITY_DENIED`
`DELEGATION_CREATED`
`DELEGATION_REVOKED`
`DELEGATION_REJECTED`

Next

Receipts and evidence: what a receipt is for.
The receipt chain: what seq, prev_hash and hash detect.
Get started · Why.

Related topics

Receipts and evidence Export to OpenTelemetry Event EventSink The Agent Control Standard