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
« 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``.
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:
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.
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.
21Without ``--apply`` nothing is deleted and the report says what would be.
22"""
24from __future__ import annotations
26import contextlib
27import json
28from dataclasses import dataclass, field
29from datetime import UTC, datetime, timedelta
30from typing import TYPE_CHECKING, Any
32from governed_harness.domain.errors import ConfigurationError
33from governed_harness.domain.models import Execution
35if TYPE_CHECKING:
36 from governed_harness.orchestration.engine_types import EngineServices
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``)."""
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
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
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
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
103class RetentionCollector:
104 def __init__(self, services: EngineServices) -> None:
105 self.s = services
107 def plan(self, now: datetime | None = None) -> RetentionPlan:
108 from governed_harness.orchestration.engine import run_is_open
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
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)
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
190 def apply(self, plan: RetentionPlan) -> None:
191 from governed_harness.orchestration.engine import RunEngine
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)
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)}
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 }