Coverage for src/governed_harness/delivery/bundle.py: 81%

236 statements  

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

1"""Portable evidence bundle (``harness export --bundle``, ``harness verify --bundle``). 

2 

3A run's evidence lives in ``.harness`` (SQLite and the artifact store) of the workspace where it 

4ran; a decision taken there cannot be checked on another machine or in CI. A bundle is a 

5``tar.gz`` archive with: 

6 

7* ``manifest.json``: the run, its status, ChangeSet digest, decision, event count and chain head, 

8 and the SHA-256 and size of every other entry (``EvidenceBundleManifest``); 

9* ``events.jsonl``: the run's event chain; 

10* ``records.json``: the run's records by type, and its task; 

11* ``artifacts/<sha256>`` and ``artifacts/<sha256>.json``: every artifact the run's events and 

12 records reference, with its descriptor (artifacts are stored redacted). 

13 

14``verify_bundle`` checks a bundle without the workspace: the entries against the manifest, the 

15event chain (sequence, links and digests) against the manifest's count and head, every artifact 

16against its digest and every decision record against the event that recorded it. A bundle is a 

17consistency check: anyone who can rewrite the whole archive can rewrite it consistently, so it 

18establishes integrity against accidental or partial changes, not authenticity.""" 

19 

20from __future__ import annotations 

21 

22import io 

23import json 

24import tarfile 

25import time 

26from collections.abc import Iterator 

27from dataclasses import dataclass, field 

28from datetime import datetime 

29from pathlib import Path, PurePosixPath 

30from typing import TYPE_CHECKING, Any 

31 

32from governed_harness import __version__ 

33from governed_harness.domain.enums import DecisionKind 

34from governed_harness.domain.errors import ConfigurationError, PolicyViolationError 

35from governed_harness.domain.models import ( 

36 BundleEntry, 

37 EvidenceBundleManifest, 

38 Execution, 

39 HumanDecision, 

40 utc_now, 

41) 

42from governed_harness.evidence.hashing import sha256_bytes, sha256_json 

43 

44if TYPE_CHECKING: 

45 from governed_harness.orchestration.engine import EngineServices 

46 

47MANIFEST = "manifest.json" 

48EVENTS = "events.jsonl" 

49RECORDS = "records.json" 

50_ARTIFACTS_DIR = "artifacts/" 

51_JSON_SUFFIX = ".json" 

52ARTIFACT_PREFIX = "artifact://sha256/" 

53DECISION_EVENT = "human.decision.recorded" 

54PRUNED_EVENT = "retention.artifacts.pruned" 

55APPROVALS = frozenset({DecisionKind.APPROVE.value, DecisionKind.APPROVE_EXCEPTION.value}) 

56MAX_MEMBER_BYTES = 512 * 1024 * 1024 

57_TAR_MTIME = 0 # deterministic member times 

58 

59 

60def artifact_refs(value: Any) -> set[str]: 

61 """Every artifact URI inside a JSON value.""" 

62 found: set[str] = set() 

63 if isinstance(value, str): 

64 if value.startswith(ARTIFACT_PREFIX): 

65 found.add(value) 

66 elif isinstance(value, dict): 

67 for item in value.values(): 

68 found |= artifact_refs(item) 

69 elif isinstance(value, list): 

70 for item in value: 

71 found |= artifact_refs(item) 

72 return found 

73 

74 

75def _record_types(services: EngineServices, execution_id: str) -> list[str]: 

76 rows = services.state.connection.execute( 

77 "SELECT DISTINCT record_type FROM records WHERE execution_id=? ORDER BY record_type", 

78 (execution_id,), 

79 ).fetchall() 

80 return [str(row["record_type"]) for row in rows] 

81 

82 

83def _add(archive: tarfile.TarFile, name: str, data: bytes) -> BundleEntry: 

84 info = tarfile.TarInfo(name) 

85 info.size = len(data) 

86 info.mtime = _TAR_MTIME 

87 info.mode = 0o600 

88 archive.addfile(info, io.BytesIO(data)) 

89 return BundleEntry(path=name, digest=sha256_bytes(data), size_bytes=len(data)) 

90 

91 

92def export_bundle(services: EngineServices, execution_id: str, output: Path) -> dict[str, Any]: 

93 """Write the bundle of a run to ``output``; refuses a run whose event chain does not 

94 verify.""" 

95 execution = services.state.get("execution", execution_id, Execution) 

96 try: 

97 services.events.verify_chain(execution_id) 

98 except ValueError as error: 

99 raise PolicyViolationError( 

100 f"the event chain of {execution_id} does not verify; not exported: {error}" 

101 ) from error 

102 events = services.events.list(execution_id) 

103 records: dict[str, list[dict[str, Any]]] = { 

104 record_type: services.state.list_dicts(record_type, execution_id=execution_id) 

105 for record_type in _record_types(services, execution_id) 

106 } 

107 records["task"] = [services.state.get_dict("task", execution.task_id)] 

108 flags = { 

109 str(row["key"]): str(row["value"]) 

110 for row in services.state.connection.execute("SELECT key, value FROM flags").fetchall() 

111 if str(row["key"]).endswith(f":{execution_id}") 

112 } 

113 refs = artifact_refs([event.as_dict() for event in events]) | artifact_refs(records) 

114 refs |= artifact_refs(list(flags.values())) 

115 refs |= {execution.configuration_snapshot_ref, execution.workflow_ref} 

116 decisions = records.get("decision", []) 

117 head = events[-1].event_digest if events else None 

118 output.parent.mkdir(parents=True, exist_ok=True) 

119 entries: list[BundleEntry] = [] 

120 missing: list[str] = [] 

121 temporary = output.with_name(f".{output.name}.{time.monotonic_ns()}.partial") 

122 try: 

123 with tarfile.open(temporary, "w:gz", format=tarfile.PAX_FORMAT) as archive: 

124 entries.append(_add(archive, EVENTS, services.events.export_jsonl(execution_id))) 

125 entries.append( 

126 _add( 

127 archive, 

128 RECORDS, 

129 json.dumps(records, sort_keys=True, indent=2, default=str).encode("utf-8"), 

130 ) 

131 ) 

132 for uri in sorted(refs): 

133 if not uri.startswith(ARTIFACT_PREFIX): 133 ↛ 134line 133 didn't jump to line 134 because the condition on line 133 was never true

134 continue 

135 hex_digest = uri[len(ARTIFACT_PREFIX) :] 

136 try: 

137 data = services.artifacts.get(uri) 

138 descriptor = services.artifacts.describe(uri) 

139 except (OSError, ValueError): 

140 missing.append(uri) 

141 continue 

142 entries.append(_add(archive, f"artifacts/{hex_digest}", data)) 

143 entries.append( 

144 _add( 

145 archive, 

146 f"artifacts/{hex_digest}.json", 

147 json.dumps( 

148 { 

149 "digest": descriptor.digest, 

150 "sizeBytes": descriptor.size_bytes, 

151 "mediaType": descriptor.media_type, 

152 "redacted": descriptor.redacted, 

153 "metadata": descriptor.metadata or {}, 

154 }, 

155 sort_keys=True, 

156 indent=2, 

157 ).encode("utf-8"), 

158 ) 

159 ) 

160 manifest = EvidenceBundleManifest( 

161 execution_id=execution_id, 

162 project_id=execution.project_id, 

163 task_id=execution.task_id, 

164 status=execution.status, 

165 current_phase=execution.current_phase, 

166 change_set_digest=execution.change_set_digest, 

167 decision_id=execution.human_decision_id, 

168 event_count=len(events), 

169 event_chain_head=head, 

170 core_version=__version__, 

171 entries=tuple(entries), 

172 ) 

173 _add( 

174 archive, 

175 MANIFEST, 

176 json.dumps(manifest.model_dump(mode="json", by_alias=True), indent=2).encode(), 

177 ) 

178 temporary.replace(output) 

179 finally: 

180 temporary.unlink(missing_ok=True) 

181 return { 

182 "bundle": str(output), 

183 "executionId": execution_id, 

184 "status": execution.status.value, 

185 "changeSetDigest": execution.change_set_digest, 

186 "decisions": [item.get("decision") for item in decisions], 

187 "eventCount": len(events), 

188 "eventChainHead": head, 

189 "entries": len(entries) + 1, 

190 "artifacts": sum( 

191 1 

192 for item in entries 

193 if item.path.startswith(_ARTIFACTS_DIR) and not item.path.endswith(_JSON_SUFFIX) 

194 ), 

195 "missingArtifacts": missing, 

196 "sizeBytes": output.stat().st_size, 

197 } 

198 

199 

200@dataclass 

201class BundleContents: 

202 manifest: EvidenceBundleManifest | None = None 

203 files: dict[str, tuple[str, int]] = field(default_factory=dict) 

204 """Entry path -> (digest, size).""" 

205 data: dict[str, bytes] = field(default_factory=dict) 

206 """The content of manifest, events and records.""" 

207 problems: list[str] = field(default_factory=list) 

208 

209 

210def _safe_name(name: str) -> bool: 

211 path = PurePosixPath(name) 

212 return bool(name) and not path.is_absolute() and ".." not in path.parts and "\\" not in name 

213 

214 

215def _members(path: Path) -> Iterator[tuple[tarfile.TarInfo, tarfile.TarFile]]: 

216 with tarfile.open(path, "r:gz") as archive: 

217 for member in archive: 

218 yield member, archive 

219 

220 

221def read_bundle(path: Path) -> BundleContents: 

222 contents = BundleContents() 

223 try: 

224 for member, archive in _members(path): 

225 if not member.isfile(): 225 ↛ 226line 225 didn't jump to line 226 because the condition on line 225 was never true

226 contents.problems.append(f"entry {member.name!r} is not a regular file") 

227 continue 

228 if not _safe_name(member.name): 228 ↛ 229line 228 didn't jump to line 229 because the condition on line 228 was never true

229 contents.problems.append(f"entry {member.name!r} has an unsafe path") 

230 continue 

231 if member.size > MAX_MEMBER_BYTES: 231 ↛ 232line 231 didn't jump to line 232 because the condition on line 231 was never true

232 contents.problems.append(f"entry {member.name!r} is larger than allowed") 

233 continue 

234 handle = archive.extractfile(member) 

235 if handle is None: 235 ↛ 236line 235 didn't jump to line 236 because the condition on line 235 was never true

236 contents.problems.append(f"entry {member.name!r} cannot be read") 

237 continue 

238 data = handle.read() 

239 contents.files[member.name] = (sha256_bytes(data), len(data)) 

240 if member.name in {MANIFEST, EVENTS, RECORDS}: 

241 contents.data[member.name] = data 

242 except (OSError, tarfile.TarError, EOFError) as error: 

243 raise ConfigurationError(f"cannot read the bundle {path}: {error}") from error 

244 raw = contents.data.get(MANIFEST) 

245 if raw is None: 245 ↛ 246line 245 didn't jump to line 246 because the condition on line 245 was never true

246 contents.problems.append("manifest.json is missing") 

247 return contents 

248 try: 

249 contents.manifest = EvidenceBundleManifest.model_validate_json(raw) 

250 except ValueError as error: 

251 contents.problems.append(f"manifest.json is not a bundle manifest: {error}") 

252 return contents 

253 

254 

255def _check_chain(lines: list[dict[str, Any]], execution_id: str) -> list[str]: 

256 problems: list[str] = [] 

257 previous: str | None = None 

258 for index, event in enumerate(lines, start=1): 

259 if event.get("executionId") != execution_id: 259 ↛ 260line 259 didn't jump to line 260 because the condition on line 259 was never true

260 problems.append(f"event {index} belongs to another run") 

261 if event.get("sequence") != index: 261 ↛ 262line 261 didn't jump to line 262 because the condition on line 261 was never true

262 problems.append(f"event sequence gap at {index}") 

263 if event.get("previousEventDigest") != previous: 263 ↛ 264line 263 didn't jump to line 264 because the condition on line 263 was never true

264 problems.append(f"previous digest mismatch at event {index}") 

265 envelope = {key: value for key, value in event.items() if key != "eventDigest"} 

266 if sha256_json(envelope) != event.get("eventDigest"): 

267 problems.append(f"event digest mismatch at event {index}") 

268 previous = event.get("eventDigest") 

269 return problems 

270 

271 

272def decision_entries(events: list[dict[str, Any]], now: datetime) -> list[dict[str, Any]]: 

273 found = [] 

274 for event in events: 

275 if event.get("eventType") != DECISION_EVENT: 

276 continue 

277 try: 

278 decision = HumanDecision.model_validate(event.get("payload") or {}) 

279 except ValueError: 

280 continue 

281 found.append( 

282 { 

283 "decisionId": decision.decision_id, 

284 "decision": decision.decision.value, 

285 "changeSetDigest": decision.change_set_digest, 

286 "actorId": decision.actor.actor_id, 

287 "decidedAt": decision.decided_at.isoformat(), 

288 "expiresAt": decision.expires_at.isoformat() if decision.expires_at else None, 

289 "expired": decision.expires_at is not None and decision.expires_at <= now, 

290 "approval": decision.decision.value in APPROVALS, 

291 } 

292 ) 

293 return found 

294 

295 

296def _entry_problems(contents: BundleContents, manifest: EvidenceBundleManifest) -> list[str]: 

297 """Entries missing, altered or unlisted, and artifacts whose name is not their digest.""" 

298 problems: list[str] = [] 

299 listed = {entry.path: entry for entry in manifest.entries} 

300 for name, entry in listed.items(): 

301 actual = contents.files.get(name) 

302 if actual is None: 302 ↛ 303line 302 didn't jump to line 303 because the condition on line 302 was never true

303 problems.append(f"entry {name} is listed but missing") 

304 elif actual != (entry.digest, entry.size_bytes): 

305 problems.append(f"entry {name} does not match its digest or size") 

306 for name in contents.files: 

307 if name != MANIFEST and name not in listed: 307 ↛ 308line 307 didn't jump to line 308 because the condition on line 307 was never true

308 problems.append(f"entry {name} is not listed in the manifest") 

309 for name, (digest, _size) in contents.files.items(): 

310 is_artifact = name.startswith(_ARTIFACTS_DIR) and not name.endswith(_JSON_SUFFIX) 

311 if is_artifact and digest != f"sha256:{name.removeprefix('artifacts/')}": 311 ↛ 312line 311 didn't jump to line 312 because the condition on line 311 was never true

312 problems.append(f"artifact {name} does not match its name") 

313 return problems 

314 

315 

316def _read_events(contents: BundleContents, problems: list[str]) -> list[dict[str, Any]]: 

317 """The events of the bundle; none (and a problem) when ``events.jsonl`` cannot be read.""" 

318 try: 

319 return [ 

320 json.loads(line) 

321 for line in contents.data.get(EVENTS, b"").decode("utf-8").splitlines() 

322 if line.strip() 

323 ] 

324 except ValueError as error: # UnicodeDecodeError is a ValueError 

325 problems.append(f"events.jsonl cannot be read: {error}") 

326 return [] 

327 

328 

329def _chain_problems(events: list[dict[str, Any]], manifest: EvidenceBundleManifest) -> list[str]: 

330 """The event chain, its length and its head against the manifest.""" 

331 problems = list(_check_chain(events, manifest.execution_id)) 

332 if len(events) != manifest.event_count: 332 ↛ 333line 332 didn't jump to line 333 because the condition on line 332 was never true

333 problems.append( 

334 f"the bundle holds {len(events)} event(s); the manifest says {manifest.event_count}" 

335 ) 

336 head = events[-1].get("eventDigest") if events else None 

337 if head != manifest.event_chain_head: 337 ↛ 338line 337 didn't jump to line 338 because the condition on line 337 was never true

338 problems.append("the last event is not the chain head of the manifest") 

339 return problems 

340 

341 

342def _read_records(contents: BundleContents, problems: list[str]) -> Any: 

343 """The records of the bundle; empty (and a problem) when ``records.json`` cannot be read.""" 

344 try: 

345 return json.loads(contents.data.get(RECORDS, b"{}")) 

346 except ValueError as error: 

347 problems.append(f"records.json cannot be read: {error}") 

348 return {} 

349 

350 

351def _record_problems(records: Any, decisions: list[dict[str, Any]]) -> list[str]: 

352 """Decision records that cannot be read or that no decision event matches.""" 

353 problems: list[str] = [] 

354 recorded = {item["decisionId"]: item for item in decisions} 

355 for raw in records.get("decision", []): 

356 try: 

357 record = HumanDecision.model_validate(raw) 

358 except ValueError: 

359 problems.append("a decision record cannot be read") 

360 continue 

361 event = recorded.get(record.decision_id) 

362 if event is None or (event["decision"], event["changeSetDigest"]) != ( 362 ↛ 366line 362 didn't jump to line 366 because the condition on line 362 was never true

363 record.decision.value, 

364 record.change_set_digest, 

365 ): 

366 problems.append(f"decision record {record.decision_id} has no matching event") 

367 return problems 

368 

369 

370def _missing_artifacts( 

371 contents: BundleContents, events: list[dict[str, Any]], records: Any 

372) -> list[str]: 

373 """Referenced artifacts that are neither in the bundle nor recorded as pruned.""" 

374 present = { 

375 name.removeprefix(_ARTIFACTS_DIR) 

376 for name in contents.files 

377 if name.startswith(_ARTIFACTS_DIR) and not name.endswith(_JSON_SUFFIX) 

378 } 

379 referenced = artifact_refs(events) | artifact_refs(records) 

380 # Artifacts that harness gc pruned under retention.artifactDays are recorded as such. 

381 pruned = { 

382 str(uri) 

383 for event in events 

384 if event.get("eventType") == PRUNED_EVENT 

385 for uri in (event.get("payload") or {}).get("artifactRefs", []) 

386 } 

387 return sorted( 

388 uri for uri in referenced - pruned if uri.removeprefix(ARTIFACT_PREFIX) not in present 

389 ) 

390 

391 

392def _manifest_summary(manifest: EvidenceBundleManifest | None) -> dict[str, Any]: 

393 """The manifest fields of a bundle report; all ``None`` without a manifest.""" 

394 if not manifest: 394 ↛ 395line 394 didn't jump to line 395 because the condition on line 394 was never true

395 return { 

396 "executionId": None, 

397 "taskId": None, 

398 "status": None, 

399 "changeSetDigest": None, 

400 "eventCount": None, 

401 "eventChainHead": None, 

402 } 

403 return { 

404 "executionId": manifest.execution_id, 

405 "taskId": manifest.task_id, 

406 "status": manifest.status.value, 

407 "changeSetDigest": manifest.change_set_digest, 

408 "eventCount": manifest.event_count, 

409 "eventChainHead": manifest.event_chain_head, 

410 } 

411 

412 

413def verify_bundle(path: Path, now: datetime | None = None) -> dict[str, Any]: 

414 """Verify a bundle without the workspace; ``valid`` is false on any problem.""" 

415 contents = read_bundle(path) 

416 problems = list(contents.problems) 

417 manifest = contents.manifest 

418 decisions: list[dict[str, Any]] = [] 

419 if manifest is not None: 419 ↛ 429line 419 didn't jump to line 429 because the condition on line 419 was always true

420 problems.extend(_entry_problems(contents, manifest)) 

421 events = _read_events(contents, problems) 

422 problems.extend(_chain_problems(events, manifest)) 

423 decisions = decision_entries(events, now or utc_now()) 

424 records = _read_records(contents, problems) 

425 problems.extend(_record_problems(records, decisions)) 

426 missing = _missing_artifacts(contents, events, records) 

427 if missing: 427 ↛ 428line 427 didn't jump to line 428 because the condition on line 427 was never true

428 problems.append(f"{len(missing)} referenced artifact(s) are not in the bundle") 

429 return { 

430 "valid": not problems, 

431 "bundle": str(path), 

432 **_manifest_summary(manifest), 

433 "decisions": decisions, 

434 "problems": problems, 

435 }