---
name: "Core Events Submodule Spec"
description: "Specification for :core:events – event sourcing backbone"
depth: 2
links: ["../index.md", "../architecture/event-model.md", "./core-module-spec.md"]
---

# :core:events module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:events` defines the canonical event sourcing model for correx.

It is the authoritative subsystem for:

* immutable event contracts
* event lifecycle semantics
* causation/correlation tracking
* replay semantics
* projection contracts
* snapshot contracts
* event ordering guarantees

`:core:events` is the foundational source of truth for all system state.

All persistent workflow state MUST originate from events defined by this module.

---

# 2. responsibilities

`:core:events` owns:

* base event contracts
* event category contracts
* event metadata semantics
* event ordering semantics
* replay contracts
* projection contracts
* snapshot contracts
* event versioning semantics
* causation/correlation semantics
* append-only guarantees
* event serialization contracts

---

# 3. non-responsibilities

`:core:events` MUST NOT own:

* database implementations
* sqlite/postgres access
* projection persistence
* websocket/event streaming transport
* telemetry exporters
* UI event rendering
* provider-specific events
* business workflow orchestration

Implementations belong to infrastructure modules.

---

# 4. architectural role

`:core:events` acts as:

* canonical state authority
* replay foundation
* audit foundation
* projection foundation
* execution history authority

All mutable runtime state MUST ultimately derive from events.

---

# 5. design principles

## 5.1 events are truth

Events are the only authoritative persistent state.

Everything else is derived.

---

## 5.2 append-only model

Events are immutable.

Existing events MUST NEVER be:

* modified
* deleted
* reordered
* rewritten

Corrections occur through compensating events only.

---

## 5.3 replay-first architecture

All workflows MUST be reconstructable exclusively from:

* event streams
* snapshots
* configs

Replayability is a mandatory architectural guarantee.

---

## 5.4 deterministic reconstruction

Given:

* identical events
* identical configs
* identical replay strategy

projection rebuild MUST produce identical results.

---

# 6. event model

## base event contract

All events MUST contain:

```kotlin
sealed interface Event {
    val id: EventId
    val sessionId: SessionId
    val timestamp: Instant
    val type: EventType
    val payload: EventPayload
    val causationId: EventId?
    val correlationId: CorrelationId?
    val sequence: Long
    val version: Int
}
```

---

## field semantics

### id

Globally unique immutable identifier.

---

### sessionId

Logical execution session ownership.

---

### timestamp

Creation time only.

Never mutated during replay.

---

### causationId

Direct parent event.

Represents:
"what caused this event to exist?"

---

### correlationId

Shared execution lineage identifier.

Used for:

* tracing
* replay grouping
* workflow reconstruction
* observability

---

### sequence

Strict append ordering within session scope.

Sequence gaps are forbidden.

---

### version

Schema evolution support.

---

# 7. event categories

Mandatory top-level categories:

```text
DomainEvents
LifecycleEvents
InferenceEvents
ToolEvents
ValidationEvents
ApprovalEvents
CompressionEvents
TransitionEvents
ProjectionEvents
SystemEvents
```

---

# 8. canonical event flow

Minimum execution flow:

```text
UserInputReceived
    ↓
SessionCreated
    ↓
StageScheduled
    ↓
ContextBuilt
    ↓
InferenceStarted
    ↓
ArtifactProduced
    ↓
ArtifactValidated
    ↓
ApprovalRequested
    ↓
TransitionExecuted
    ↓
SessionCompleted
```

Real workflows may branch but MUST remain replayable.

---

# 9. ordering guarantees

## required guarantees

Within a session:

* ordering MUST be deterministic
* append order MUST be preserved
* replay order MUST match append order

---

## forbidden behavior

Forbidden:

* out-of-order mutation
* concurrent sequence conflicts
* nondeterministic replay ordering

---

# 10. event ownership rules

Every event MUST have exactly one:

* producer
* ownership boundary

Example:

```text
ToolEvents
  owned by :core:tools

ApprovalEvents
  owned by :core:approvals
```

Cross-module event mutation is forbidden.

---

# 11. replay model

Supported replay modes:

* full replay
* replay from cursor
* replay until condition
* deterministic simulation
* projection-only replay
* inference-skipping replay

Replay MUST function without:

* live models
* live tools
* provider access

---

# 12. projection model

## projection definition

Projection:
deterministic derived state built from events.

---

## projection guarantees

Projections MUST be:

* disposable
* rebuildable
* deterministic
* side-effect free

---

## projection restrictions

Projections MUST NOT:

* mutate events
* emit side effects
* perform orchestration
* own workflow authority

---

# 13. snapshot model

Snapshots exist only to optimize replay.

Snapshots are:

* optimization artifacts
* rebuildable
* disposable

Snapshots MUST NEVER become authoritative state.

---

## snapshot guarantees

Snapshots MUST contain:

* originating event sequence
* projection version
* snapshot timestamp

---

# 14. versioning model

Event schemas MUST support forward evolution.

Rules:

* old events remain replayable
* incompatible mutations forbidden
* event meaning immutable after release

Schema migrations MUST occur through:

* versioned deserialization
* compensating events
* projection migration logic

Never through historical mutation.

---

# 15. serialization requirements

Events MUST support deterministic serialization.

Requirements:

* stable field ordering
* explicit schema versions
* portable encoding
* replay-safe decoding

Recommended:

* kotlinx.serialization

Forbidden:

* reflection-dependent serialization
* provider-specific encoding

---

# 16. concurrency model

Event append semantics MUST remain:

* atomic
* ordered
* idempotent

Concurrent appends MUST NOT create:

* duplicate sequence numbers
* replay ambiguity
* partial visibility

---

# 17. idempotency guarantees

Replay MUST be idempotent.

Reapplying identical events MUST produce:

* identical projections
* identical state transitions

Duplicate event processing MUST be detectable.

---

# 18. observability requirements

`:core:events` MUST expose tracing metadata for:

* causation chains
* correlation chains
* replay timelines
* projection rebuild timing
* event append latency
* snapshot timing

---

# 19. failure semantics

Event append failures MUST:

* fail atomically
* emit structured failures
* never partially commit

Projection rebuild failures MUST:

* preserve original events
* isolate projection corruption
* support rebuild retries

---

# 20. security boundaries

Events are trusted as historical records but not as semantic truth.

Semantic correctness MUST still be validated externally.

Sensitive payload handling MUST support:

* redaction policies
* secret isolation
* audit-safe serialization

---

# 21. extension model

Extensions MAY:

* introduce new event types
* introduce projections
* introduce replay consumers

Extensions MUST NOT:

* mutate existing events
* rewrite history
* bypass append ordering
* bypass replay semantics

---

# 22. forbidden patterns

Forbidden:

* mutable events
* in-place updates
* hidden side-channel state
* projection-owned truth
* replay-dependent side effects
* event deletion
* unordered append semantics
* timestamp-based replay ordering

---

# 23. persistence expectations

Persistence implementations MUST support:

* append-only writes
* ordered reads
* replay scans
* snapshot storage
* cursor-based replay
* optimistic concurrency

Storage engines are infrastructure concerns.

---

# 24. testing requirements

`:core:events` MUST support deterministic testing for:

* replay correctness
* ordering guarantees
* idempotency
* snapshot rebuild
* projection rebuild
* sequence integrity
* version compatibility

---

# 25. philosophy summary

`:core:events` exists to externalize all workflow state into immutable observable history.

Reliability emerges from:

* append-only history
* deterministic replay
* rebuildable projections
* explicit causality
* immutable execution lineage

not from mutable runtime memory.
