# Events, Audit, Realtime and Telemetry

**Status:** Approved target-state baseline  
**First realization:** I0

## Target State

AWP keeps four related but non-interchangeable concepts explicit:

```text
Business Event = durable product fact
Audit          = attributable action/decision trail
Realtime       = low-latency non-authoritative projection
Telemetry      = logs, metrics, traces for operation/debugging
```

A fifth concept, `Notification`, is a user-facing communication derived from product state/events and belongs to the communications domain.

## Invariants From Day 1

- lifecycle-changing transactions persist required business event/audit atomically;
- business event IDs and aggregate revisions support deduplication/order reasoning;
- realtime loss never loses product truth;
- telemetry loss never changes lifecycle outcome;
- audit records identify Principal, action, target, time and relevant Decision/Approval/Attempt context;
- secrets/sensitive payloads are redacted/classified before logs/realtime/notifications;
- provider webhooks are observations normalized through adapters, not business events until AWP accepts a transition;
- UI can rebuild current state after disconnect from authoritative APIs/read models.

## Business Event Envelope

Conceptually:

```text
Event {
  id
  type
  occurredAt
  aggregateType
  aggregateId
  aggregateRevision
  principalId?
  correlationId
  causationId?
  payloadVersion
  payload
}
```

External event publishing may use CloudEvents envelope conventions. Internal event names remain AWP semantics.

## Audit Model

Audit covers both successful and denied/high-risk actions where useful. It records authority provenance without duplicating full secret/request bodies.

Examples:

- user accepts/rejects a Planning recommendation;
- AWP creates delegated technical Decision;
- trusted publisher creates branch/merge;
- production Approval granted/denied;
- agent Attempt starts with resolved provider/account/model;
- policy blocks a capability;
- connection permission changes.

## Realtime

Realtime channels are keyed by durable identities such as Project, Plan, FactoryRun, AgentRun, CIExecution or Deployment. Events carry revision/sequence markers. Clients that detect gaps/stale state re-query.

Realtime may be served/fanned out by gateway infrastructure, but gateway has no authority to invent lifecycle transitions.

## Telemetry

OpenTelemetry-compatible instrumentation/export is the boundary. Required baseline signals:

- trace/correlation across gateway -> control -> workflow -> provider;
- structured logs with domain IDs but no secrets;
- operational metrics for queue/runs/provider errors/latency/resource state;
- execution-plane workload/node telemetry needed for dogfood safety.

A particular persistent telemetry backend/Collector is deployment configuration, not a domain dependency.

## Retention and Privacy

Product events/audit have explicit retention and access policy. Telemetry may have shorter/operational retention. Research/user-content payloads and agent chat/tool logs may contain sensitive material and must be classified separately from ordinary metrics.

## Increment Realization

| Increment | Event/observability realization |
|---|---|
| I0 | event/audit/outbox foundation, correlation IDs, base telemetry. |
| I1 | Factory/Attempt/ChangeSet/Review/Merge events and enough realtime to operate lifecycle. |
| I4 | rich agent/tool/diff/checkpoint streams and Factory projections. |
| I5–I8 | CI, deployment, cluster and incident event families. |
| I9 | enterprise retention/export controls and reliability/SLO telemetry consumption. |

## Current Implementation State

Observability is designed in from the first persistence schema rather than retrofitted after UI implementation.

## Deferred Realization

Advanced analytics warehouses, long-term trace backends and enterprise audit export are later deployment/product capabilities behind the same event/audit contracts.

## Temporary Dogfood Behavior

Dogfood may retain fewer days of telemetry, but business event/audit identity and lifecycle coverage cannot be skipped.

## Decisions / ADRs

CloudEvents and OpenTelemetry are boundary standards, not product authorities. Changes to event ownership require architecture Decision review.