> ## 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`   |

### 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](/concepts/receipts-and-evidence): what a receipt is for.
* [The receipt chain](/security/receipt-chain): what `seq`, `prev_hash` and `hash` detect.
* [Get started](/get-started/quickstart) · [Why](/why).


## Related topics

- [Receipts and evidence](/concepts/receipts-and-evidence.md)
- [Export to OpenTelemetry](/guides/export-to-opentelemetry.md)
- [Event](/reference/api/Event.md)
- [EventSink](/reference/api/EventSink.md)
- [The Agent Control Standard](/ACS.md)