567 lines
8.3 KiB
Markdown
567 lines
8.3 KiB
Markdown
---
|
||
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.
|