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:

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.

3.4 KiB Raw Permalink Blame History Unescape Escape