Coverage for src/governed_harness/orchestration/engine_types.py: 100%

88 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""Types and constants the engine shares with its helpers (#69): its paths and services, the 

2outcome of a phase step, of a read-only agent call and of the independent review, and the 

3effective testing strategy. 

4 

5They live apart from ``engine``, ``agent_results``, ``agent_review`` and ``engineering`` so that 

6the helpers can build a ``PhaseOutcome`` and type what they share without importing their owner 

7or a sibling: an import back into the owner closed a module cycle. The modules that defined them 

8re-export them.""" 

9 

10from __future__ import annotations 

11 

12from dataclasses import dataclass 

13from pathlib import Path 

14from typing import Any 

15 

16from governed_harness.agents.environment import secret_values 

17from governed_harness.configuration.models import ResolvedConfiguration 

18from governed_harness.domain.enums import ResultStatus 

19from governed_harness.domain.models import Finding 

20from governed_harness.events import SQLiteEventStore 

21from governed_harness.evidence import LocalArtifactStore, SecretRedactor 

22from governed_harness.runtime.state_location import resolve_state_location 

23from governed_harness.storage import SQLiteStateStore 

24 

25TASK_REVISION_DIGEST_FLAG = "taskrevdigest:" 

26"""State flag prefix (+ execution id) of the digest of the task revision pinned to a run.""" 

27 

28 

29@dataclass(frozen=True) 

30class EnginePaths: 

31 workspace: Path 

32 harness_dir: Path 

33 database: Path 

34 artifact_dir: Path 

35 state_root: Path | None = None 

36 """The run registry outside the workspace (``runtime.stateDir`` or an isolated run's 

37 origin, #55); ``None`` when the state lives in ``.harness/`` as in 1.0.0.""" 

38 

39 @classmethod 

40 def from_workspace(cls, workspace: Path) -> EnginePaths: 

41 root = workspace.resolve(strict=True) 

42 harness_dir = root / ".harness" 

43 harness_dir.mkdir(parents=True, exist_ok=True, mode=0o700) 

44 return cls(root, harness_dir, harness_dir / "state.db", harness_dir / "artifacts") 

45 

46 @classmethod 

47 def for_project(cls, resolved: ResolvedConfiguration) -> EnginePaths: 

48 """The paths of a resolved project: ``.harness/`` for the workspace's own files and the 

49 state location ``runtime.stateDir`` (or an isolation marker) names for the registry.""" 

50 paths = cls.from_workspace(resolved.workspace_root) 

51 location = resolve_state_location( 

52 paths.workspace, resolved.project.project_id, resolved.project.runtime.state_dir 

53 ) 

54 if not location.external: 

55 return paths 

56 return cls( 

57 paths.workspace, 

58 paths.harness_dir, 

59 location.database, 

60 location.artifacts, 

61 location.root, 

62 ) 

63 

64 

65@dataclass 

66class EngineServices: 

67 resolved: ResolvedConfiguration 

68 paths: EnginePaths 

69 state: SQLiteStateStore 

70 events: SQLiteEventStore 

71 artifacts: LocalArtifactStore 

72 

73 @classmethod 

74 def open(cls, resolved: ResolvedConfiguration) -> EngineServices: 

75 paths = EnginePaths.for_project(resolved) 

76 return cls( 

77 resolved=resolved, 

78 paths=paths, 

79 state=SQLiteStateStore(paths.database), 

80 events=SQLiteEventStore(paths.database), 

81 artifacts=LocalArtifactStore( 

82 paths.artifact_dir, 

83 SecretRedactor( 

84 literals=secret_values(resolved.project), 

85 extended=bool(resolved.project.runtime.extended_redaction), 

86 ), 

87 ), 

88 ) 

89 

90 def pin_task_revision(self, execution_id: str, uri: str, digest: str) -> None: 

91 """Pin the stored task revision ``uri`` to a run (``governance.pinTaskRevision``) with 

92 the digest of the task as it was given: when the stored revision is redacted (#178), 

93 the run works on the stored task only while it still has that digest.""" 

94 self.state.set_flag(f"taskrev:{execution_id}", uri) 

95 self.state.set_flag(f"{TASK_REVISION_DIGEST_FLAG}{execution_id}", digest) 

96 

97 def close(self) -> None: 

98 self.state.close() 

99 self.events.close() 

100 

101 

102@dataclass(frozen=True) 

103class PhaseOutcome: 

104 status: ResultStatus 

105 summary: str 

106 evidence_refs: tuple[str, ...] = () 

107 artifact_refs: tuple[str, ...] = () 

108 

109 

110READ_ONLY_RULE = "agent.read-only-violation" 

111"""Rule id of the finding recorded when a read-only agent call changed the workspace.""" 

112 

113 

114@dataclass(frozen=True) 

115class AgentCallOutcome: 

116 """What a read-only agent call returned: its status, the structured result when it passed 

117 and the evidence it left.""" 

118 

119 status: ResultStatus 

120 summary: str 

121 result: dict[str, Any] | None 

122 invocation_id: str | None 

123 evidence_refs: tuple[str, ...] 

124 protocol_error: str | None = None 

125 """Since #80: why the answer broke the provider protocol (no JSON, no ``result``).""" 

126 workspace_violation: str | None = None 

127 """Since #92: the call changed the workspace (undone, ``agent.read-only-violation``) and its 

128 answer was discarded; under ``runtime.contractRetry`` the call is sent once more.""" 

129 

130 

131@dataclass(frozen=True) 

132class ReviewOutcome: 

133 """Whether the independent review ran and the findings of it that block.""" 

134 

135 ran: bool 

136 blocking: tuple[Finding, ...] = () 

137 

138 

139@dataclass(frozen=True) 

140class Strategy: 

141 """The effective testing strategy and where it came from.""" 

142 

143 name: str 

144 """``tdd``, ``bdd``, ``conventional`` or ``unknown`` (the ``testing.strategy`` value).""" 

145 source: str 

146 """``configuration``, ``project-setup`` (a person's answer), ``detected`` or ``unknown``.""" 

147 frameworks: tuple[str, ...] = () 

148 

149 @property 

150 def strategy(self) -> str: 

151 """The strategy's name, as the callers and the ``strategy`` key of ``as_dict`` read it.""" 

152 return self.name 

153 

154 def as_dict(self) -> dict[str, Any]: 

155 return { 

156 "strategy": self.name, 

157 "source": self.source, 

158 "frameworks": list(self.frameworks), 

159 } 

160 

161 

162__all__ = [ 

163 "READ_ONLY_RULE", 

164 "TASK_REVISION_DIGEST_FLAG", 

165 "AgentCallOutcome", 

166 "EnginePaths", 

167 "EngineServices", 

168 "PhaseOutcome", 

169 "ReviewOutcome", 

170 "Strategy", 

171]