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