---
name: "Event Model"
description: "Canonical event structure, categories, and causality"
depth: 2
links: 
  - "../index.md"
  - "./overview.md"
  - "./replay-model.md"
---

# event model

**version:** 0.1-draft  
**status:** architectural reference

---

## 1. purpose

Events are the sole source of truth for all workflow state in correx. Every meaningful action (user input, stage start, artifact produced, approval granted, transition executed) is recorded as an immutable event.

---

## 2. event structure

Every event contains:

```kotlin
sealed interface Event {
    val id: EventId
    val sessionId: SessionId
    val timestamp: Instant
    val type: EventType
    val payload: EventPayload
    val causationId: EventId?      // what directly caused this event?
    val correlationId: CorrelationId? // which workflow/execution lineage?
    val sequence: Long              // strict append order within session
    val version: Int                // schema version
}
```

---

## 3. event categories

| category | owner module | examples |
|----------|--------------|----------|
| DomainEvents | core:events, core:artifacts | ArtifactProduced, ArtifactSuperseded |
| LifecycleEvents | core:sessions | SessionCreated, SessionCompleted |
| InferenceEvents | core:inference | InferenceStarted, InferenceCompleted |
| ToolEvents | core:tools | ToolInvocationRequested, ToolExecutionCompleted |
| ValidationEvents | core:validation | ArtifactValidated, ArtifactRejected |
| ApprovalEvents | core:approvals | ApprovalRequested, ApprovalGranted |
| CompressionEvents | core:context | ContextPackBuilt, CompressionApplied |
| TransitionEvents | core:transitions | TransitionExecuted, StageScheduled |
| ProjectionEvents | core:events | ProjectionRebuilt |
| SystemEvents | various | WatchdogTimeout, ProviderHealthChanged |

---

## 4. causal chain (simplified)

```
UserInputReceived
  └→ SessionCreated
       └→ StageScheduled
            └→ ContextPackBuilt
                 └→ InferenceStarted
                      └→ ArtifactProduced
                           └→ ArtifactValidated
                                ├→ (if approval needed) ApprovalRequested → ApprovalGranted
                                └→ TransitionExecuted
                                     └→ (next stage)
```

Causation IDs form an explicit directed acyclic graph; every event can be traced back to its origin.

---

## 5. ordering and append guarantees

* Events are append‑only. Existing events are never modified or deleted.
* Sequence numbers are strictly increasing within a session, gap‑free.
* Compensating events (e.g., `ArtifactSuperseded`) are themselves new events; they do not alter history.
* Ordering during replay must exactly match the original insertion order.

---

## 6. replay semantics

Given a sequence of events, replay rebuilds all projections and workflow state deterministically. For inference‑skipping replay, artifacts and validation outcomes are read directly from recorded events rather than re‑invoking models.

---

## 7. snapshotting

Snapshots are periodically rebuilt from event streams to speed up replay. They are **disposable optimisation artifacts**; the event log remains the authority.

---

## 8. extension and versioning

New event types may be added by core modules or plugins. Schema evolution is handled via version numbers and migration logic that never alters historical events.