8.3 KiB
name, description, depth, links
| name | description | depth | links | |||
|---|---|---|---|---|---|---|
| Core Events Submodule Spec | Specification for :core:events – event sourcing backbone | 2 |
|
: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:
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:
DomainEvents
LifecycleEvents
InferenceEvents
ToolEvents
ValidationEvents
ApprovalEvents
CompressionEvents
TransitionEvents
ProjectionEvents
SystemEvents
8. canonical event flow
Minimum execution flow:
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:
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.