correx/core/kernel/AGENTS.md

core/kernel — AGENTS.md

Purpose

Top-level orchestration: drives session lifecycle through workflow stages, coordinates retries, manages approval gating, runs static analysis, and provides deterministic replay of past sessions.

Ownership

CORREX kernel team. This is the integration point for all other core/ modules. Changes here affect end-to-end session behavior.

Local Contracts

• SessionOrchestrator / DefaultSessionOrchestrator — primary entry point for launching and advancing sessions through workflow stages.
• OrchestrationState / OrchestrationReducer (DefaultOrchestrationReducer) / OrchestrationProjector / OrchestrationRepository — standard event-sourcing stack for orchestration state.
• RetryCoordinator / DefaultRetryCoordinator — manages retry logic per RetryPolicy.
• ApprovalGateway — kernel-side approval bridge; calls core:approvals engine before executing gated operations.
• ReplayOrchestrator / ReplayInferenceProvider / ReplayStrategy — deterministic replay of a session from its event log. ReplayInferenceProvider returns recorded responses — no live LLM (Hard Invariant #8).
• SubagentRunner / InSessionSubagentRunner — runs sub-agent invocations within an active session.
• StaticAnalysisRunner / ProcessStaticAnalysisRunner — runs static analysis tools and records results as events.
• StageCheckpointReconciler — reconciles checkpoint state across stage transitions.
• JournalCompactionService — triggers journal compaction and emits JournalCompactedEvent.
• OrchestratorEngines / OrchestratorRepositories — dependency bundles for wiring.
• WorkspaceContext / WorkspaceToolRegistryProvider — workspace-scoped tool registry provisioning.
• RepoKnowledgeRetriever — retrieves repo knowledge facts recorded as events (Hard Invariant #9: observations recorded at query time, not re-queried during replay).
• BriefEchoDiff / BriefReferenceExtractor — brief grounding utilities.
• CritiqueOutcomeCorrelator — correlates critique findings with orchestration outcomes for calibration.
• ContextFeedback — feeds context signals back into the orchestration loop.
• PreemptRedirect — handles steering/preempt events mid-session.
• ReplayArtifactMissingException — thrown when replay requires an artifact that was not recorded.

Work Guidance

• Follow the standard Events→State→Reducer→Projector→Repository pattern (see core/AGENTS.md).
• DefaultOrchestrationReducer only does state.copy(...). All routing decisions live in DefaultSessionOrchestrator.
• Hard Invariant #3: DefaultSessionOrchestrator decides; LLM proposals from core:inference are inputs, not decisions.
• Hard Invariant #4: ApprovalGateway must be called before any gated operation. Policy denial is terminal.
• Hard Invariant #8: ReplayOrchestrator must never call a live provider. Use ReplayInferenceProvider.
• OrchestratorEngines and OrchestratorRepositories are the canonical wiring containers. Add new dependencies there, not as ad-hoc constructor params scattered across callers.

Verification

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

Tests in testing/kernel/ (RetryCoordinator, ReplayInferenceProvider, LaunchRegistrationRace, ContextFeedback) and testing/replay/ (session replay, execution plan, refinement, repo knowledge replay).

Child DOX Index

No child AGENTS.md (leaf module).