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
« 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``).
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:
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).
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."""
20from __future__ import annotations
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
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
44if TYPE_CHECKING:
45 from governed_harness.orchestration.engine import EngineServices
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
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
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]
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))
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 }
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)
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
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
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
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
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
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
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 []
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
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 {}
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
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 )
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 }
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 }