epic-12: after epic audit and init commit

docs/modules/core-transitions-submodule-spec.md

@@ -0,0 +1,503 @@
+---
+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.