> ## Documentation Index
> Fetch the complete documentation index at: https://ctrlrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Receipt and event schemas

> Every field of a ctrlrun receipt and of an event, and every event type, rendered from the dataclasses that write them.

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` and `prev_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.

**Two rows are about the object rather than the document**, and the difference matters
when you are reading a JSONL line rather than a `Receipt`. Every line begins with
`"schema": "ctrlrun.receipt/v3"`, which is written by the serializer and is not a field
below. And `hash` **is** a field below and is *not* in the line: a document cannot
contain its own hash, so the store keeps it in a column and `chain_hash()` recomputes
it. A reader checking a chain compares those two.

| 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` |
| `precondition_at_request` | \`str | None\` | `None` |
| `precondition_at_recheck` | \`str | None\` | `None` |
| `approvers` | `tuple` | `()` | |
| `authority_grant_id` | \`str | None\` | `None` |
| `task` | \`str | None\` | `None` |
| `scope_hash` | \`str | None\` | `None` |
| `hop` | \`str | None\` | `None` |
| `budget_charges` | `tuple` | `()` | |
| `schema` | `str` | `'ctrlrun.receipt/v7'` | |
| `_stored_document` | \`collections.abc.Mapping\[str, Any] | 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` |
| `CLOCK_SKEW_DETECTED` |

## Next

* [Receipts and evidence](/docs/concepts/receipts-and-evidence): what a receipt is for.
* [The receipt chain](/docs/security/receipt-chain): what `seq`, `prev_hash` and `hash` detect.
* [Get started](/docs/get-started/quickstart) · [Why](/docs/why).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.