> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Event sourcing: choosing the source of truth

Event sourcing stores an aggregate's authoritative changes as an ordered event
stream. Reconstructing state applies those events in sequence. State reconstruction
must reproduce recorded decisions deterministically.

## A conceptual example

A hypothetical event-sourced Project could apply `ProjectOpened`,
`ProjectMemberAdded` and `ProjectMemberRemoved` to reconstruct its membership.
These are illustrative event names. The current Project implementation restores
saved authoritative state.

<a href="/source/services/beto/contexts/project/domain/project.go.txt">Source: project.go</a>

```go
func RestoreProject(snapshot ProjectSnapshot) (*Project, error) {
	if err := snapshot.Validate(); err != nil {
		return nil, tactical.Corrupt(err.Error())
	}
	return &Project{state: snapshot.Copy()}, nil
}
```

Restoration validates a saved snapshot and raises no new facts. Reconstructing state
must not trigger provider effects or reinterpret historical choices using today's
external information.

## Snapshots and projections

An event-sourcing snapshot caches state at a known stream revision. The retained
stream remains authoritative. In current-state persistence, the saved aggregate
snapshot itself can be authoritative. Identify which meaning applies before
designing replay or recovery.

A projection is a derived view. Rebuilding it requires a source that retains enough
information and a recovery contract; an outbox may discard confirmed deliveries.

| Mechanism             | Role in this platform                            |
| --------------------- | ------------------------------------------------ |
| Saved aggregate state | Current business authority                       |
| Domain facts          | Owner-local change semantics                     |
| Integration events    | Published contracts for other contexts           |
| Outbox                | Durable publication intent and retry bookkeeping |
| Receipts              | Durable evidence of accepted or executed work    |
| Dead-letter replay    | Controlled delivery retry                        |

## Adoption needs a decision

The platform defaults to current-state persistence. Adopting event sourcing needs
an explicit owner-scoped decision covering stream schemas, append concurrency,
restoration, evolution, sensitive-data retention, migration and recovery tests.

The reference repository retains `es` in its name but also documents current-state
persistence. Importing its educational material does not change this platform's
storage policy. Read [DDD.md](/reference/DDD.md) and
[the architecture](/reference/ARCHITECTURE.md).

Next: [Testing and exercises](/learn/testing-and-exercises.md).

Adapted from the [architecture reference](/learn/attribution.md), with Pharos examples.

<details class="page-source"><summary>Page source</summary>

<a href="/source/docs/content/learn/event-sourcing.md.txt">Source snapshot</a> · Revision `f928834c8`.

</details>