kami
45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# 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 `TransitionEdge`s.
|
|
- `TransitionResolver` / `DefaultTransitionResolver` — evaluates `TransitionCondition`s 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.
|
|
- `BuildExpectation` resolves toolchain-scoped command aliases (`node.build`, `jvm.build`) before legacy flat aliases, keeping profile snapshots replayable.
|
|
- Cycle detection (`CycleExtractor`) runs during graph validation (`core:validation`), not at runtime.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
./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).
|