epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,566 @@
+---
+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.