kami/correx

Fork 0

Files

T

kami c77277af0b epic-12: after epic audit and init commit

2026-05-17 03:19:39 +04:00

7.6 KiB

Raw Blame History

name, description, depth, links

name

description

depth

links

Core Transitions Submodule Spec

Specification for :core:transitions – workflow graph engine

../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:

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:

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:

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