docs(dox): build out the DOX AGENTS.md hierarchy

Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,43 @@
+# 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
+
+```bash
+./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).