504 lines
7.6 KiB
Markdown
504 lines
7.6 KiB
Markdown
---
|
||
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.
|