Coverage for src/governed_harness/orchestration/retention.py: 92%

138 statements  

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

1"""``harness gc``: apply ``retention.artifactDays`` and ``retention.eventDays``. 

2 

3Both settings were written by ``harness init`` and read by nothing. Their semantics here, for 

4runs that ended (closed, cancelled or rejected; an open run is never touched) longer ago than 

5the setting, counted from the run's last update: 

6 

7* ``artifactDays``: the run's artifacts (configuration snapshot, baseline, diffs, validator 

8 output, evidence, trace) are deleted from ``.harness/artifacts`` unless a run that is kept 

9 references the same content, and a ``retention.artifacts.pruned`` event on the run's chain 

10 lists them, so ``harness verify`` reports them as pruned rather than missing. The events and 

11 records stay. 

12* ``eventDays``: the run is removed entirely: its events, its records (memory records stay), 

13 its flags and the artifacts no kept run references. 

14 

15Since 2.0, ``retention.orphanArtifacts: true`` also deletes the artifacts nothing references: 

16no record, flag or event of any run or of the project names them (left by runs removed before 

17the setting, by an interrupted write, or by a version that did not record a reference). An 

18artifact written in the last hour is never an orphan, so a run that is writing its evidence in 

19another process keeps it. 

20 

21Without ``--apply`` nothing is deleted and the report says what would be. 

22""" 

23 

24from __future__ import annotations 

25 

26import contextlib 

27import json 

28from dataclasses import dataclass, field 

29from datetime import UTC, datetime, timedelta 

30from typing import TYPE_CHECKING, Any 

31 

32from governed_harness.domain.errors import ConfigurationError 

33from governed_harness.domain.models import Execution 

34 

35if TYPE_CHECKING: 

36 from governed_harness.orchestration.engine_types import EngineServices 

37 

38PRUNED_EVENT = "retention.artifacts.pruned" 

39_ARTIFACT_PREFIX = "artifact://sha256/" 

40KEPT_RECORD_TYPES = frozenset({"memory", "task"}) 

41ORPHAN_GRACE_SECONDS = 3600 

42"""An artifact younger than this is never an orphan (``retention.orphanArtifacts``).""" 

43 

44 

45@dataclass 

46class RetentionPlan: 

47 artifact_days: int | None 

48 event_days: int | None 

49 removed_runs: list[str] = field(default_factory=list) 

50 pruned_runs: dict[str, list[str]] = field(default_factory=dict) 

51 artifacts: list[str] = field(default_factory=list) 

52 orphan_artifacts: bool | None = None 

53 orphans: list[str] = field(default_factory=list) 

54 orphan_bytes: int = 0 

55 

56 def as_dict(self, applied: bool) -> dict[str, Any]: 

57 report: dict[str, Any] = { 

58 "applied": applied, 

59 "artifactDays": self.artifact_days, 

60 "eventDays": self.event_days, 

61 "removedRuns": self.removed_runs, 

62 "prunedRuns": sorted(self.pruned_runs), 

63 "artifactsRemoved": len(self.artifacts), 

64 "artifacts": self.artifacts, 

65 } 

66 if self.orphan_artifacts is not None: 66 ↛ 71line 66 didn't jump to line 71 because the condition on line 66 was always true

67 report["orphanArtifacts"] = self.orphan_artifacts 

68 report["orphansRemoved"] = len(self.orphans) 

69 report["orphanBytes"] = self.orphan_bytes 

70 report["orphans"] = self.orphans 

71 return report 

72 

73 

74def _days(retention: dict[str, Any], key: str) -> int | None: 

75 value = retention.get(key) 

76 if value is None: 76 ↛ 77line 76 didn't jump to line 77 because the condition on line 76 was never true

77 return None 

78 if isinstance(value, bool) or not isinstance(value, int) or value < 0: 78 ↛ 79line 78 didn't jump to line 79 because the condition on line 78 was never true

79 raise ConfigurationError(f"retention.{key} must be a whole number of days: {value!r}") 

80 days: int = value 

81 return days 

82 

83 

84def _artifact_refs(value: Any) -> set[str]: 

85 """Every artifact URI inside a JSON value, including a JSON document held in a string (a 

86 flag such as ``implstart:<run>`` or ``agentsnapshots:<run>``).""" 

87 found: set[str] = set() 

88 if isinstance(value, str): 

89 if value.startswith(_ARTIFACT_PREFIX): 

90 found.add(value) 

91 elif value[:1] in {"{", "["} and _ARTIFACT_PREFIX in value: 

92 with contextlib.suppress(ValueError): 

93 found |= _artifact_refs(json.loads(value)) 

94 elif isinstance(value, dict): 

95 for item in value.values(): 

96 found |= _artifact_refs(item) 

97 elif isinstance(value, list): 

98 for item in value: 

99 found |= _artifact_refs(item) 

100 return found 

101 

102 

103class RetentionCollector: 

104 def __init__(self, services: EngineServices) -> None: 

105 self.s = services 

106 

107 def plan(self, now: datetime | None = None) -> RetentionPlan: 

108 from governed_harness.orchestration.engine import run_is_open 

109 

110 retention = dict(self.s.resolved.project.retention) 

111 plan = RetentionPlan(_days(retention, "artifactDays"), _days(retention, "eventDays")) 

112 moment = now or datetime.now(UTC) 

113 runs = self.s.state.list( 

114 "execution", Execution, project_id=self.s.resolved.project.project_id 

115 ) 

116 kept: set[str] = set() 

117 candidates: set[str] = set() 

118 for run in runs: 

119 age = moment - run.updated_at 

120 ended = not run_is_open(run) 

121 refs = self._references(run) 

122 if ended and plan.event_days is not None and age >= timedelta(days=plan.event_days): 

123 plan.removed_runs.append(run.execution_id) 

124 candidates |= refs 

125 elif ( 

126 ended 

127 and plan.artifact_days is not None 

128 and age >= timedelta(days=plan.artifact_days) 

129 ): 

130 pruned = refs - self._pruned(run.execution_id) 

131 if pruned: 131 ↛ 118line 131 didn't jump to line 118 because the condition on line 131 was always true

132 plan.pruned_runs[run.execution_id] = sorted(pruned) 

133 candidates |= pruned 

134 else: 

135 kept |= refs 

136 plan.artifacts = sorted(candidates - kept) 

137 removable = set(plan.artifacts) 

138 plan.pruned_runs = { 

139 run_id: [uri for uri in uris if uri in removable] 

140 for run_id, uris in plan.pruned_runs.items() 

141 if any(uri in removable for uri in uris) 

142 } 

143 self._orphans(plan, retention, moment, removable) 

144 return plan 

145 

146 def _orphans( 

147 self, 

148 plan: RetentionPlan, 

149 retention: dict[str, Any], 

150 moment: datetime, 

151 removable: set[str], 

152 ) -> None: 

153 """Apply ``retention.orphanArtifacts``: when true, plan the orphan artifacts too.""" 

154 orphans = retention.get("orphanArtifacts") 

155 if orphans is None: 155 ↛ 156line 155 didn't jump to line 156 because the condition on line 155 was never true

156 return 

157 if not isinstance(orphans, bool): 157 ↛ 158line 157 didn't jump to line 158 because the condition on line 157 was never true

158 raise ConfigurationError( 

159 f"retention.orphanArtifacts must be true or false: {orphans!r}" 

160 ) 

161 plan.orphan_artifacts = orphans 

162 if orphans: 162 ↛ exitline 162 didn't return from function '_orphans' because the condition on line 162 was always true

163 self._plan_orphans(plan, moment, removable) 

164 

165 def _plan_orphans(self, plan: RetentionPlan, moment: datetime, planned: set[str]) -> None: 

166 referenced: set[str] = set() 

167 connection = self.s.state.connection 

168 for row in connection.execute("SELECT payload_json FROM records"): 

169 if _ARTIFACT_PREFIX in row["payload_json"]: 

170 referenced |= _artifact_refs(json.loads(row["payload_json"])) 

171 for row in connection.execute("SELECT value FROM flags"): 

172 referenced |= _artifact_refs(str(row["value"])) 

173 for event in self.s.events.list_all(): 

174 referenced |= _artifact_refs(event.payload) 

175 grace = (moment - timedelta(seconds=ORPHAN_GRACE_SECONDS)).timestamp() 

176 for path in sorted(self.s.artifacts.meta_root.glob("*.json")): 

177 uri = f"{_ARTIFACT_PREFIX}{path.stem}" 

178 if uri in referenced or uri in planned: 

179 continue 

180 try: 

181 stat = path.stat() 

182 except OSError: 

183 continue 

184 if stat.st_mtime > grace: 

185 continue 

186 plan.orphans.append(uri) 

187 blob = self.s.artifacts.blob_root / path.stem[:2] / path.stem[2:] 

188 plan.orphan_bytes += blob.stat().st_size if blob.exists() else 0 

189 

190 def apply(self, plan: RetentionPlan) -> None: 

191 from governed_harness.orchestration.engine import RunEngine 

192 

193 for uri in [*plan.artifacts, *plan.orphans]: 

194 self.s.artifacts.delete(uri) 

195 engine = RunEngine(self.s) 

196 for run_id, uris in plan.pruned_runs.items(): 

197 self.s.events.append( 

198 run_id, 

199 PRUNED_EVENT, 

200 {"artifactRefs": uris, "artifactDays": plan.artifact_days}, 

201 ) 

202 engine.anchor_chain(run_id) 

203 for run_id in plan.removed_runs: 

204 self.s.events.delete_execution(run_id) 

205 self.s.state.delete_execution(run_id, keep=KEPT_RECORD_TYPES) 

206 

207 def _references(self, run: Execution) -> set[str]: 

208 refs = {run.configuration_snapshot_ref, run.workflow_ref} 

209 for record_type in self.s.state.record_types(run.execution_id): 

210 if record_type in KEPT_RECORD_TYPES: 210 ↛ 211line 210 didn't jump to line 211 because the condition on line 210 was never true

211 continue 

212 for item in self.s.state.list_dicts(record_type, execution_id=run.execution_id): 

213 refs |= _artifact_refs(item) 

214 refs |= _artifact_refs(self.s.state.flags_for(run.execution_id)) 

215 return {ref for ref in refs if ref.startswith(_ARTIFACT_PREFIX)} 

216 

217 def _pruned(self, execution_id: str) -> set[str]: 

218 return { 

219 str(uri) 

220 for event in self.s.events.list(execution_id) 

221 if event.event_type == PRUNED_EVENT 

222 for uri in event.payload.get("artifactRefs", []) 

223 }