ADR-007 Event-driven audit trail
| Status | Accepted |
| Date | 2026-09-20 |
Context
Release is a high-risk workflow. Post-hoc reconstruction from application logs is not good enough. Questions about who changed a policy, who confirmed a contact, and what was delivered need a single append-only trail with a stable schema.
Decision
Security-sensitive state changes emit domain events defined in contracts/events/catalog.md. The audit module persists those events. It is not optional logging.
Events are facts about ids, states, evidence codes, and provider outcomes. They are not copies of vault bodies.
The owner activity timeline and any future operational dashboard are projections of this stream. They must not be fed by a parallel, divergent log.
If the audit write fails, the domain transaction fails.
Consequences
- Modules take a dependency on the event contract, not on a specific log vendor.
- Observability tooling (metrics, traces) remains useful and is not the audit trail. A trace that contains instruction text is a defect.
- A later
observabilityrepository may subscribe to the same events. It does not redefine them.