correx/core/transitions/AGENTS.md

core/transitions — AGENTS.md

Purpose

FSM/workflow graph execution: defines the WorkflowGraph (stages and transition edges), resolves which transition to take at each step, executes stages, and detects cycles.

Ownership

CORREX kernel team.

Local Contracts

• WorkflowGraph — the workflow DAG: stages (StageConfig) connected by TransitionEdges.
• TransitionResolver / DefaultTransitionResolver — evaluates TransitionConditions against EvaluationContext to pick the next stage.
• TransitionCondition — sealed interface for conditions. Built-in: AlwaysTrue, VariableEquals, ArtifactFieldEquals, ArtifactConditions, and composites (Composites).
• StageExecutor — executes a single stage given a StageExecutionRequest; returns StageExecutionResult.
• StageExecutionEventMapper / DefaultStageExecutionEventMapper — maps stage execution results to domain events.
• TransitionDecision / TransitionOrdering — decision and ordering types.
• EvaluationContext — runtime context for condition evaluation.
• PromptResolver — resolves prompt templates for a stage from config.
• CycleExtractor / CycleDfs / DetectedCycle / CycleCanonicalizer — detect and canonicalize cycles in the workflow graph (used by core:validation).
• DeterministicAdjacencyBuilder / GraphOrdering — deterministic graph traversal for consistent ordering.
• VisitState — DFS traversal state.

Work Guidance

• DefaultTransitionResolver is stateless per call — it reads EvaluationContext, not persisted state.
• Stage events are recorded by DefaultStageExecutionEventMapper; the mapper must emit events for every outcome (success, failure, skip).
• WorkflowGraph is built from config/TOML at session start; it is immutable during a session.
• StageConfig.autoBuildGate is a compiler-set request for a runtime build gate; it is used on write-declaring freestyle stages only when no explicit build expectation exists.
• Cycle detection (CycleExtractor) runs during graph validation (core:validation), not at runtime.

Verification

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

Tests in testing/transitions/ (DefaultTransitionResolverTest, TransitionFuzzTest, TransitionEventSerializationTest) and testing/replay/ (TransitionReplayIntegrationTest).

Child DOX Index

No child AGENTS.md (leaf module).