correx/core/AGENTS.md

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

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