correx/core/events/AGENTS.md

core/events — AGENTS.md

Purpose

Foundational event-sourcing infrastructure: all EventPayload definitions for every domain, the serialization registry, the EventStore interface, the EventReplayer contract, and shared identity/vocabulary types used across the entire core/ layer.

Ownership

CORREX kernel team. This is the most cross-cutting module in the codebase — changes here can break every other module. Coordinate before adding or renaming event types.

Local Contracts

• EventPayload — sealed interface that every domain event implements.
• StoredEvent / EventEnvelope / EventMetadata — envelope types wrapping payloads for storage and replay.
• EventStore — interface for appending and querying events. Implementations in infrastructure/.
• EventReplayer<S> / DefaultEventReplayer<S> — replays a filtered event stream through a Projection<S> to rebuild state.
• Projection<S> — interface: initial(): S + apply(state, event): S.
• StateBuilder / DefaultStateBuilder — convenience builder over EventReplayer.
• Serialization.kt — the eventModule polymorphic block. Every new EventPayload subclass must be registered here. Missing registration = silent deserialization failure.
• JsonEventSerializer / EventSerializer — serialize/deserialize StoredEvent to JSON.
• EventDispatcher — broadcasts events to in-process listeners.
• Domain event files: ApprovalEvents, ArtifactEvents, ContextEvents, InferenceEvents, OrchestrationEvents, RouterEvents, SessionEvents, TaskEvents, ToolEvents, IntentEvents, RiskAssessedEvent, JournalCompactedEvent, and many more — all payload definitions live here.
• Shared vocabulary: IdentityTypes (SessionId, TaskId, etc.), Tier, TokenUsage, ToolReceipt, ToolRequest, RiskLevel, RetryPolicy, GrantScope, GrantLedger.

Work Guidance

• SILENT FAILURE TRAP: After adding any EventPayload subclass, immediately add it to Serialization.kt eventModule block. Run ./gradlew check to verify. Tests may pass without it but runtime replay will fail silently.
• AnyMapSerializer — custom serializer for Map<String, Any?>; use it for dynamic payloads, don't roll another.
• Event classes are @Serializable data class with no mutable state. No methods beyond data accessors.
• Do not add domain logic to events. They are records, not actors.
• EgressAllowlistProjection — special projection kept in this module because it is used by both core:toolintent and core:events consumers; it is a shared cross-cutting projection.

Verification

./gradlew :core:events:test --rerun-tasks

Tests in testing/contracts/ (EventsTest, EventStoreContractTest) and testing/replay/ (serialization round-trips, replay integration).

Child DOX Index

No child AGENTS.md (leaf module).