> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0047 — Audit service fed by events

> Proposed · 2026-10-19

## Context

Models can opt in to auditing ([0046](/adr/0046-global-data-invariants-and-per-model-opt-ins)), the AI engine writes audit events
([0021](/adr/0021-ai-engine-and-agent-write-safety)), and operator endpoints must be audited
([0051](/adr/0051-better-auth-identity-service)). An audit trail written by each service into its own database cannot be queried
or retained as one, and a trail written inside the same transaction as the change couples every service to it. Cross-service
communication is by published events ([0014](/adr/0014-data-ownership-and-orm) decision 4).

## Decision

1. **A single audit service owns the audit store.** No other service reads or writes its tables.
2. **Services publish audit events; the audit service consumes them.** A service never calls the audit store directly.
3. **An audit event carries** actor, tenant, action, target type and id, time, and request id. It never carries secret values or PII field contents; changed-field names only.
4. **Delivery is at-least-once and consumption is idempotent**, keyed by event id.
5. **The audit store is append-only** to its consumers. Retention period: TODO.
6. **Tenants can read their own audit events**; operators can read across tenants through an audited endpoint.

## Consequences

* One place to answer "who did what", needed for the SOC 2 target.
* An audit event can lag its change; it is not a synchronous guard.
* Reliable publication depends on the outbox pattern, which is a separate decision.

## Enforcement

Planned — a contract test that the audit event schema has no free-text value field, and a lint rule banning imports of the audit service's tables. Nothing is implemented yet.

## Supersedes and sources

Supersedes: none. Sources: owner decisions in chat, 2026-10-19.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.