103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
---
|
||
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. |