# core/ — AGENTS.md

## Purpose

Pure domain logic for CORREX: event sourcing primitives, session orchestration, inference routing, tool management, workflow graph execution, and all supporting domain services. No I/O, no external adapters.

## Ownership

All modules under `core/` are owned by the CORREX kernel team. Changes to shared event types (in `core:events`) require review for downstream impact across all modules.

## Local Contracts

- Dependency direction: `apps → core → infrastructure`. No cross-core imports. No sibling module dependencies within `core/`.
- Shared vocabulary types belong in `core:events` only.
- Constructor parameters use interfaces wherever an interface exists. Concrete classes are never instantiated inside another class.
- All state is rebuilt from events. State is never persisted independently.
- Every new `EventPayload` subclass must be registered in `core/events/.../serialization/Serialization.kt` inside the `eventModule` polymorphic block. Missing registration causes silent runtime deserialization failure.

## Work Guidance

Follow the standard domain module pattern for every module in this subtree:

1. **Events** — `@Serializable data class` implementing `EventPayload`, defined in `core:events`.
2. **State** — module-local `@Serializable data class` with sensible empty defaults. Always rebuilt from events.
3. **Reducer** — `interface ThingReducer` + `DefaultThingReducer`. Only `state.copy(...)` logic, no domain decisions.
4. **Projector** — `class ThingProjector(reducer)` implementing `Projection<ThingState>`.
5. **Repository** — `DefaultThingRepository(replayer: EventReplayer<ThingState>)`. Wired as `DefaultEventReplayer(store, ThingProjector(DefaultThingReducer()))`.

**Hard Invariants (all apply here):**
1. Event log is the only source of truth.
2. Projections are bounded-context owned — no shared global state, no cross-projection mutation.
3. LLMs propose; core decides. LLM outputs are untrusted until validated.
4. Policy layer is absolute — approvals cannot override policy denial.
5. All tools declare execution tier. All tool side effects captured in events.
6. Compression is non-authoritative — derived representations must not replace original events.
7. Replay is environment-independent — no external service calls, no live LLM required.
8. Environment observations are recorded as events at the moment they occur, never re-queried during replay.

**Kotlin rules:**
- `runCatching { }` over bare try/catch.
- Scope functions (`?.let`, `?:`) over null-branching `if/else`.
- `suspend` + `delay()`, never `Thread.sleep()`. Blocking I/O in `withContext(Dispatchers.IO)`.
- Never swallow `CancellationException`.
- Verify all imports are used before finalizing any file.

## Verification

```bash
./gradlew check                                  # full suite: tests + detekt + koverVerify
./gradlew :core:<module>:test --rerun-tasks      # single module, bypass cache
```

Many tests live in `testing/` submodules (approvals, contracts, deterministic, kernel, projections, replay, transitions) — check there before concluding a module has no tests.

## Child DOX Index

- [approvals/](approvals/AGENTS.md) — approval gate engine: grants, modes, policy enforcement
- [artifacts/](artifacts/AGENTS.md) — structured output model: artifact kinds, lineage, relationships
- [artifacts-store/](artifacts-store/AGENTS.md) — artifact persistence interface
- [config/](config/AGENTS.md) — TOML config loading, operator/project profile, agent instructions
- [context/](context/AGENTS.md) — context synthesis, compression, token budgeting
- [critique/](critique/AGENTS.md) — critic calibration state and projector
- [events/](events/AGENTS.md) — event primitives, serialization registry, replay infrastructure
- [inference/](inference/AGENTS.md) — provider abstraction, routing, prompt rendering, embedder
- [journal/](journal/AGENTS.md) — decision journal projection and memory distillation
- [kernel/](kernel/AGENTS.md) — top-level orchestration: SessionOrchestrator, retry, replay
- [risk/](risk/AGENTS.md) — risk assessment and tier mapping
- [router/](router/AGENTS.md) — router facade, context building, L3 memory, idea capture
- [sessions/](sessions/AGENTS.md) — session lifecycle, state, approval mode binding
- [tasks/](tasks/AGENTS.md) — task graph, board, markdown, git sync, context assembly
- [toolintent/](toolintent/AGENTS.md) — plane-2 tool-call intent validation and workspace policy
- [tools/](tools/AGENTS.md) — tool contract, registry, executor, output compression
- [transitions/](transitions/AGENTS.md) — FSM/workflow graph, stage execution, cycle detection
- [validation/](validation/AGENTS.md) — layered validation pipeline: graph, semantic, session, JSON schema