Coverage for src/governed_harness/orchestration/state_machine.py: 77%
57 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1from __future__ import annotations
3from dataclasses import dataclass
5from governed_harness.domain.enums import PhaseId, ResultStatus
8class InvalidTransition(ValueError):
9 pass
12PHASE_ORDER: tuple[PhaseId, ...] = (
13 PhaseId.INTENT,
14 PhaseId.DISCOVERY,
15 PhaseId.SPECIFICATION,
16 PhaseId.PLANNING,
17 PhaseId.IMPLEMENTATION,
18 PhaseId.VERIFICATION,
19 PhaseId.INDEPENDENT_REVIEW,
20 PhaseId.DECISION,
21 PhaseId.CLOSURE,
22)
25@dataclass(frozen=True)
26class TransitionDecision:
27 source: PhaseId
28 target: PhaseId
29 invalidated: tuple[PhaseId, ...] = ()
32class NormativeStateMachine:
33 def advance(
34 self, phase: PhaseId, result: ResultStatus, *, required: bool = True
35 ) -> TransitionDecision:
36 accepted = result is ResultStatus.PASSED or (
37 not required and result is ResultStatus.NOT_APPLICABLE
38 )
39 if not accepted:
40 raise InvalidTransition(f"phase {phase} cannot advance with {result}")
41 try:
42 index = PHASE_ORDER.index(phase)
43 except ValueError as error:
44 raise InvalidTransition(f"phase is not in the primary workflow: {phase}") from error
45 if index == len(PHASE_ORDER) - 1: 45 ↛ 46line 45 didn't jump to line 46 because the condition on line 45 was never true
46 raise InvalidTransition("CLOSURE has no next primary phase")
47 return TransitionDecision(source=phase, target=PHASE_ORDER[index + 1])
49 def authorize_correction(self, phase: PhaseId) -> TransitionDecision:
50 if phase is not PhaseId.DECISION: 50 ↛ 51line 50 didn't jump to line 51 because the condition on line 50 was never true
51 raise InvalidTransition("correction may only be authorized from DECISION")
52 return TransitionDecision(
53 source=PhaseId.DECISION,
54 target=PhaseId.IMPLEMENTATION,
55 invalidated=(
56 PhaseId.VERIFICATION,
57 PhaseId.INDEPENDENT_REVIEW,
58 PhaseId.DECISION,
59 PhaseId.CLOSURE,
60 ),
61 )
63 def authorize_verification_correction(self, phase: PhaseId) -> TransitionDecision:
64 """The automatic correction of ``runtime.verificationCorrections``: a failed
65 VERIFICATION returns to IMPLEMENTATION and its result stops counting, as after a
66 REQUEST_CHANGES decision."""
67 if phase is not PhaseId.VERIFICATION:
68 raise InvalidTransition("an automatic correction may only start from VERIFICATION")
69 return TransitionDecision(
70 source=PhaseId.VERIFICATION,
71 target=PhaseId.IMPLEMENTATION,
72 invalidated=(
73 PhaseId.VERIFICATION,
74 PhaseId.INDEPENDENT_REVIEW,
75 PhaseId.DECISION,
76 PhaseId.CLOSURE,
77 ),
78 )
80 def authorize_reverification(self, phase: PhaseId) -> TransitionDecision:
81 """Since 2.0 (``verification.reverifyOnChange``, #78): a ChangeSet that changed outside
82 the run while it waited in DECISION is verified again; the gate and any decision on
83 the earlier ChangeSet stop counting."""
84 if phase is not PhaseId.DECISION: 84 ↛ 85line 84 didn't jump to line 85 because the condition on line 84 was never true
85 raise InvalidTransition("a re-verification may only start from DECISION")
86 return TransitionDecision(
87 source=PhaseId.DECISION,
88 target=PhaseId.VERIFICATION,
89 invalidated=(
90 PhaseId.VERIFICATION,
91 PhaseId.INDEPENDENT_REVIEW,
92 PhaseId.DECISION,
93 PhaseId.CLOSURE,
94 ),
95 )
97 def authorize_review_correction(self, phase: PhaseId) -> TransitionDecision:
98 """Since 2.0 (``review.agentReview``, #38): blocking findings of the second reviewer
99 return INDEPENDENT_REVIEW to IMPLEMENTATION within the correction budget."""
100 if phase is not PhaseId.INDEPENDENT_REVIEW: 100 ↛ 101line 100 didn't jump to line 101 because the condition on line 100 was never true
101 raise InvalidTransition("a review correction may only start from INDEPENDENT_REVIEW")
102 return TransitionDecision(
103 source=PhaseId.INDEPENDENT_REVIEW,
104 target=PhaseId.IMPLEMENTATION,
105 invalidated=(
106 PhaseId.VERIFICATION,
107 PhaseId.INDEPENDENT_REVIEW,
108 PhaseId.DECISION,
109 PhaseId.CLOSURE,
110 ),
111 )
113 def authorize_next_subtask(self, phase: PhaseId) -> TransitionDecision:
114 """Since 2.0 (``planning.decomposition``, #39): a sub-task whose gate passed hands the
115 workspace to the next sub-task's IMPLEMENTATION."""
116 if phase is not PhaseId.VERIFICATION: 116 ↛ 117line 116 didn't jump to line 117 because the condition on line 116 was never true
117 raise InvalidTransition("the next sub-task may only start after VERIFICATION")
118 return TransitionDecision(
119 source=PhaseId.VERIFICATION,
120 target=PhaseId.IMPLEMENTATION,
121 invalidated=(PhaseId.INDEPENDENT_REVIEW, PhaseId.DECISION, PhaseId.CLOSURE),
122 )
124 def authorize_replanning(self, phase: PhaseId) -> TransitionDecision:
125 """Since 2.0 (``planning.granularity: adaptive``, #39): a coarse attempt that failed
126 its corrections returns to PLANNING to be decomposed."""
127 if phase is not PhaseId.VERIFICATION: 127 ↛ 128line 127 didn't jump to line 128 because the condition on line 127 was never true
128 raise InvalidTransition("replanning may only start after VERIFICATION")
129 return TransitionDecision(
130 source=PhaseId.VERIFICATION,
131 target=PhaseId.PLANNING,
132 invalidated=(
133 PhaseId.IMPLEMENTATION,
134 PhaseId.VERIFICATION,
135 PhaseId.INDEPENDENT_REVIEW,
136 PhaseId.DECISION,
137 PhaseId.CLOSURE,
138 ),
139 )
141 def authorize_acceptance_revision(self, phase: PhaseId) -> TransitionDecision:
142 """Since 2.0 (``verification.acceptanceTests.disputes``, #94): a person who agrees
143 that a frozen acceptance test is wrong sends a failed VERIFICATION back to
144 SPECIFICATION, where new tests are proposed, approved and frozen. The plan and the
145 implementation stand: VERIFICATION runs again on the same change."""
146 if phase is not PhaseId.VERIFICATION: 146 ↛ 147line 146 didn't jump to line 147 because the condition on line 146 was never true
147 raise InvalidTransition("an acceptance revision may only start from VERIFICATION")
148 return TransitionDecision(
149 source=PhaseId.VERIFICATION,
150 target=PhaseId.SPECIFICATION,
151 invalidated=(
152 PhaseId.SPECIFICATION,
153 PhaseId.VERIFICATION,
154 PhaseId.INDEPENDENT_REVIEW,
155 PhaseId.DECISION,
156 PhaseId.CLOSURE,
157 ),
158 )
160 @staticmethod
161 def approval_is_current(approved_digest: str, current_digest: str) -> bool:
162 return approved_digest == current_digest
164 @staticmethod
165 def can_resume(status: ResultStatus) -> bool:
166 return status in {
167 ResultStatus.PENDING,
168 ResultStatus.RUNNING,
169 ResultStatus.BLOCKED,
170 ResultStatus.FAILED,
171 ResultStatus.INCONCLUSIVE,
172 ResultStatus.TIMED_OUT,
173 ResultStatus.ERROR,
174 ResultStatus.INTERRUPTED,
175 }