---
summary: Append-only history of an entry's status transitions, stored as a JSONL companion next to index.md.
---
# Event log
The **event log** is the append-only history of every entry,
stored as an `events.jsonl` companion file sibling to `index.md`.
Throughput, lead time, cycle time — these read straight from the
log; the workspace itself is the time series, no separate
database needed.
## Shape
One JSON object per line. Each event has exactly two fields:
- `timestamp` — when the action happened (RFC 3339 UTC).
- `action` — what happened, with kind-specific fields.
```jsonl
{"timestamp":"2026-04-29T14:32:00Z","action":{"name":"created","status":"open"}}
{"timestamp":"2026-05-03T10:15:42Z","action":{"name":"status_changed","from":"open","to":"in-progress"}}
```
The file lives alongside `index.md` in the same entry directory.
Appending a new event is `open(O_APPEND) + write(line + "\n")` —
no read, no re-serialisation, no rewrite of prior content.
Two action shapes ship in the binary; the set is closed:
- `created` — first entry of every log; carries the initial
status given by the configured workflow.
- `status_changed` — every transition; carries `from` and `to`.
## Configuration
None. The action vocabulary lives in the binary, not in
`cartulary.toml`.
## Validation
`cartu check` enforces:
- The `events.jsonl` sibling is present.
- The first event is always `created`.
- The `created` event's `status` matches the configured initial
status for its kind.
- Each `status_changed` walks an allowed transition declared in
the [status](concept://status) workflow.
- The journal's terminal `to` value matches the entry's
frontmatter `status:` field.
- Once a terminal status closes the lifecycle, no further events
follow.
## Commands
The event log is read-only — `cartu issue status update` and
`cartu adr status update` append to it as a side effect of
status transitions. To read it, `cartu issue show <id>` prints
the entry's history;
`cartu issue metrics summary` and `cartu issue metrics distribution` aggregate
across the workspace.