# Provenance Ledger

> Log every agent decision and state change to an immutable append-only ledger with full metadata — so any past action can be explained, audited, or reversed on demand.

- **Category**: Agentic AI
- **Subcategory**: Governance & Observability
- **Canonical URL**: https://designpattern.fyi/patterns/provenance_ledger/

---

## Description
**Intent**: Log every agent decision and state change with enough metadata to explain or reverse it later.
**Context**: An agent that approves insurance claims, modifies production records, or sends money will eventually face a regulator, customer, or internal auditor asking why it did what it did on a specific date. Answering requires the action, the reasoning chain, retrieved evidence, and model version that surrounded it — weeks or months after the fact.
**Solution**: Append events to an immutable log with: timestamp, actor, action, target, justification (link to thought or decision), diff hash. Enable rollback by event id. Reject events that lack required fields.



## Use Cases
- Agent decisions and state changes must be explainable or reversible after the fact.
- An immutable, append-only log can be operated and queried.
- Each event can carry timestamp, actor, action, target, and justification fields.






## Trade-offs


### Advantages

- Audit and rollback become tractable — not forensic guesswork.

- Failure patterns become visible across time — you can see clusters of bad decisions.




### Considerations & Drawbacks

- Log volume can dominate storage at scale — requires retention and archiving policies.

- Justification fields require the agent to populate them; lazy or prompt-shortchanged agents skip them.







---
**Reference**: [Original Source](https://www.agentpatternscatalog.org/patterns/provenance-ledger/)