--- 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.