# Events and Audit Schema Contract

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

## Business Event Envelope

```text
BusinessEvent<T> {
  id
  type
  schemaVersion
  occurredAt
  aggregateType
  aggregateId
  aggregateRevision
  projectId?
  principalId?
  correlationId
  causationId?
  payload: T
}
```

Events state durable accepted product facts, not raw provider messages. External publication can wrap the same semantics in CloudEvents.

## Audit Record

```text
AuditRecord {
  id
  occurredAt
  principalId
  action
  targetType
  targetId
  projectId?
  disposition
  policyId/revision?
  decisionId?
  approvalId?
  correlationId
  safeMetadata
}
```

Audit captures attribution/authorization context and may record denied high-risk attempts. It does not copy full secrets/source payloads by default.

## Realtime Projection

Realtime messages can carry event/projection delta with sequence/revision. They are explicitly non-authoritative and may be dropped/coalesced; clients recover from API state.

## Provider Observation

Provider webhook/observation uses adapter-owned schema with provider delivery ID, verified source/account/resource, native payload version and observedAt. Adapter translates it before any domain event is emitted.

## Versioning

Event type + `schemaVersion` is independently versioned from aggregate revision. Consumers declare supported versions. Breaking event changes use new version/type with migration/dual-read strategy where persisted consumers exist.

## Ordering

No global total order is assumed. Aggregate revision plus correlation/causation supports local lifecycle order. Cross-aggregate workflows rely on durable orchestration/application invariants rather than arrival order alone.

## Deduplication

Event IDs unique. Provider delivery dedupe keys are provider/account/delivery scoped. Consumer side effects are idempotent and persist consumption where necessary.

## Privacy / Classification

Payload schemas mark sensitive source/chat/research/user data. Secrets/tokens are never present. Retention may differ between business events, audit, agent activity logs and telemetry.

## Increment Realization

I0 event/audit/outbox schemas. Each activated domain adds event payloads under these rules. I9 adds enterprise export/retention interfaces rather than a second audit model.

## Acceptance

A consumer can identify what changed, on which aggregate/revision, under which correlation/Principal, and safely retry/deduplicate without treating telemetry/provider events as product truth.