---
name: "Core Transitions Submodule Spec"
description: "Specification for :core:transitions – workflow graph engine"
depth: 2
links: ["../index.md", "./core-module-spec.md", "./core-validation-submodule-spec.md"]
---

# :core:transitions module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:transitions` defines the deterministic workflow transition engine for correx.

It is the authoritative subsystem for:

* workflow graph semantics
* transition evaluation
* stage progression
* condition evaluation
* retry semantics
* branching semantics
* deadlock/cycle detection
* execution progression guarantees

`:core:transitions` determines:

* what execution path is legal
* when workflow state may advance
* how failures propagate
* how retries are controlled

---

# 2. responsibilities

`:core:transitions` owns:

* workflow graph contracts
* transition contracts
* transition evaluation semantics
* condition evaluation
* retry policies
* branching semantics
* terminal state semantics
* cycle detection
* deadlock detection
* transition replay semantics
* execution progression guarantees

---

# 3. non-responsibilities

`:core:transitions` MUST NOT own:

* model inference
* tool execution
* persistence implementations
* websocket streaming
* projection persistence
* approval implementation
* context synthesis
* provider management

`:core:transitions` decides legality of progression only.

---

# 4. architectural role

`:core:transitions` acts as:

* deterministic workflow state machine
* execution progression authority
* orchestration legality validator
* workflow graph evaluator

All workflow progression MUST pass through this subsystem.

---

# 5. design principles

## 5.1 transitions are deterministic

Transition evaluation MUST depend only on:

* current projections
* current workflow config
* current event history

Transition evaluation MUST NOT depend on:

* hidden runtime state
* provider internals
* model memory
* nondeterministic mutable state

---

## 5.2 workflow graphs are explicit

All execution paths MUST be explicitly declared.

Implicit execution flow is forbidden.

---

## 5.3 transitions are validated

All transitions MUST be validated before execution.

Invalid transitions MUST fail explicitly.

---

## 5.4 retries are state-aware

Retries MUST evaluate:

* current projections
* side effects
* prior failures
* retry policies

Blind retries are forbidden.

---

# 6. workflow graph model

## graph definition

A workflow graph consists of:

```text id="3d3shm"
Stages
Transitions
Conditions
Terminal states
Retry rules
Failure rules
Approval gates
```

---

## graph guarantees

Workflow graphs MUST be:

* deterministic
* acyclic unless explicitly declared cyclic
* statically validated
* replay-safe

---

# 7. stage model

## stage definition

A stage represents:

* one bounded execution unit
* one orchestration checkpoint
* one validation boundary

Stages MUST have:

* unique identifier
* declared inputs
* declared outputs
* declared transition rules

---

# 8. transition model

## transition definition

A transition represents:

* legal movement between stages

Transitions MUST define:

* source stage
* target stage
* condition set
* retry behavior
* failure behavior

---

## transition guarantees

Transitions MUST:

* emit events
* remain replayable
* remain deterministic
* remain validation-aware

---

# 9. condition evaluation model

Conditions MAY evaluate:

* artifact fields
* projections
* approvals
* validation outcomes
* policy outcomes
* retry counters

---

## condition guarantees

Condition evaluation MUST be:

* side-effect free
* deterministic
* replay-safe

---

## forbidden condition behavior

Forbidden:

* network access
* filesystem mutation
* model execution
* tool execution
* hidden mutable state access

---

# 10. transition DSL requirements

Transition definitions MUST support:

```yaml id="6dqarf"
when:
  all:
    - artifact.status == "valid"
    - projection.open_risks < 2
    - approval.tier <= T2
```

Required features:

* boolean composition
* projection queries
* artifact queries
* retry conditions
* approval conditions

---

# 11. retry model

Retries MUST be:

* bounded
* explicit
* evented
* replayable

Retries MUST evaluate:

* prior failures
* side effects
* policy restrictions
* retry budget

---

## retry guarantees

Retries MUST NOT:

* loop infinitely
* ignore state mutation
* bypass validation
* bypass approvals

---

# 12. failure propagation model

Failures MAY:

* retry current stage
* branch to recovery stage
* escalate approval
* terminate session
* pause workflow

Failure behavior MUST be explicitly declared.

---

# 13. branching semantics

Supported branching:

* linear progression
* conditional branching
* recovery branching
* retry branching
* terminal branching

Parallel execution MAY be introduced later but is not required initially.

---

# 14. terminal state semantics

Mandatory terminal outcomes:

```text id="avqvsv"
COMPLETED
FAILED
CANCELLED
BLOCKED
```

Terminal states MUST:

* stop progression
* emit lifecycle events
* preserve replay integrity

---

# 15. cycle detection

Workflow validation MUST detect:

* unintended cycles
* unreachable stages
* dead transitions
* infinite retry loops

Explicit cycles MUST require:

* explicit configuration
* bounded termination conditions

---

# 16. deadlock detection

Transition validation MUST detect:

* approval deadlocks
* retry deadlocks
* dependency deadlocks
* unreachable terminal states

Invalid graphs MUST fail at config load time.

---

# 17. transition execution guarantees

Transitions MUST:

* occur atomically
* emit events
* preserve ordering
* preserve replay consistency

Partial transitions are forbidden.

---

# 18. replay guarantees

Transition replay MUST reproduce:

* stage progression
* branching decisions
* retry decisions
* terminal outcomes

Replay MUST NOT require:

* live models
* live tools
* provider access

---

# 19. observability requirements

`:core:transitions` MUST expose telemetry hooks for:

* transition evaluation
* branching decisions
* retry timelines
* deadlock detection
* graph traversal
* stage duration
* failure propagation

---

# 20. security boundaries

Transition logic defines execution legality boundaries.

Transitions MUST NOT:

* bypass approvals
* bypass validation
* bypass policies
* bypass session lifecycle constraints

Untrusted plugins MUST NOT gain direct transition authority.

---

# 21. extension model

Extensions MAY define:

* custom conditions
* custom retry policies
* custom transition evaluators
* custom branching strategies

Extensions MUST remain:

* deterministic
* replay-safe
* side-effect free

---

# 22. forbidden patterns

Forbidden:

* implicit workflow progression
* hidden branching
* infinite retries
* nondeterministic evaluation
* transition mutation during execution
* replay-dependent branching
* provider-dependent transition legality

---

# 23. persistence expectations

Transition persistence MUST support:

* transition history
* retry history
* branching history
* replay reconstruction

Persistence implementations belong to infrastructure modules.

---

# 24. testing requirements

`:core:transitions` MUST support deterministic testing for:

* graph validation
* condition evaluation
* retry handling
* deadlock detection
* cycle detection
* branching correctness
* replay reconstruction

---

# 25. philosophy summary

`:core:transitions` exists to constrain orchestration into deterministic legal workflow progression.

Reliability emerges from:

* explicit graphs
* deterministic conditions
* bounded retries
* validated branching
* replayable execution flow

not from trusting model autonomy.
