Coverage for src/governed_harness/events/sqlite_store.py: 90%

135 statements  

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

1from __future__ import annotations 

2 

3import builtins 

4import json 

5import sqlite3 

6import threading 

7from collections.abc import Iterable 

8from dataclasses import dataclass 

9from datetime import UTC, datetime 

10from pathlib import Path 

11from types import TracebackType 

12from typing import Any, Self 

13 

14from governed_harness.domain.models import HARNESS_ACTOR, Actor 

15from governed_harness.evidence.hashing import sha256_json 

16 

17 

18@dataclass(frozen=True) 

19class StoredEvent: 

20 event_id: str 

21 sequence: int 

22 execution_id: str 

23 event_type: str 

24 occurred_at: str 

25 actor: dict[str, Any] 

26 payload: dict[str, Any] 

27 previous_digest: str | None 

28 event_digest: str 

29 phase_execution_id: str | None = None 

30 causation_id: str | None = None 

31 correlation_id: str | None = None 

32 redaction_version: str = "1" 

33 

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

35 return { 

36 "schemaVersion": "1.0", 

37 "eventId": self.event_id, 

38 "executionId": self.execution_id, 

39 "phaseExecutionId": self.phase_execution_id, 

40 "causationId": self.causation_id, 

41 "correlationId": self.correlation_id, 

42 "sequence": self.sequence, 

43 "eventType": self.event_type, 

44 "occurredAt": self.occurred_at, 

45 "actor": self.actor, 

46 "payload": self.payload, 

47 "previousEventDigest": self.previous_digest, 

48 "eventDigest": self.event_digest, 

49 "redactionVersion": self.redaction_version, 

50 } 

51 

52 

53class EventChainError(ValueError): 

54 pass 

55 

56 

57@dataclass(frozen=True) 

58class ChainCheck: 

59 """The result of walking the event chain of one run.""" 

60 

61 valid: bool 

62 event_count: int 

63 head_digest: str | None 

64 """Digest of the last event that verified (the head of the chain when ``valid``).""" 

65 head_sequence: int | None 

66 error: str | None = None 

67 

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

69 return { 

70 "valid": self.valid, 

71 "eventCount": self.event_count, 

72 "headSequence": self.head_sequence, 

73 "headDigest": self.head_digest, 

74 "error": self.error, 

75 } 

76 

77 

78class SQLiteEventStore: 

79 def __init__(self, path: Path) -> None: 

80 path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) 

81 self.path = path 

82 self.connection = sqlite3.connect(path, timeout=30, check_same_thread=False) 

83 self.connection.row_factory = sqlite3.Row 

84 self.connection.execute("PRAGMA journal_mode=WAL") 

85 self.connection.execute("PRAGMA synchronous=FULL") 

86 self.connection.execute("PRAGMA foreign_keys=ON") 

87 self.connection.execute("PRAGMA busy_timeout=30000") 

88 self._lock = threading.RLock() 

89 self.connection.execute( 

90 """ 

91 CREATE TABLE IF NOT EXISTS events ( 

92 global_sequence INTEGER PRIMARY KEY AUTOINCREMENT, 

93 event_id TEXT NOT NULL UNIQUE, 

94 execution_id TEXT NOT NULL, 

95 execution_sequence INTEGER NOT NULL, 

96 event_type TEXT NOT NULL, 

97 occurred_at TEXT NOT NULL, 

98 actor_json TEXT NOT NULL, 

99 payload_json TEXT NOT NULL, 

100 phase_execution_id TEXT, 

101 causation_id TEXT, 

102 correlation_id TEXT, 

103 previous_digest TEXT, 

104 event_digest TEXT NOT NULL UNIQUE, 

105 redaction_version TEXT NOT NULL, 

106 UNIQUE(execution_id, execution_sequence) 

107 ) 

108 """ 

109 ) 

110 self.connection.execute( 

111 "CREATE INDEX IF NOT EXISTS events_execution_idx ON events(execution_id, execution_sequence)" 

112 ) 

113 self.connection.commit() 

114 

115 def append( 

116 self, 

117 execution_id: str, 

118 event_type: str, 

119 payload: dict[str, Any], 

120 *, 

121 actor: Actor = HARNESS_ACTOR, 

122 event_id: str | None = None, 

123 phase_execution_id: str | None = None, 

124 causation_id: str | None = None, 

125 correlation_id: str | None = None, 

126 redaction_version: str = "1", 

127 ) -> StoredEvent: 

128 with self._lock, self.connection: 

129 return self._insert( 

130 execution_id, 

131 event_type, 

132 payload, 

133 actor=actor, 

134 event_id=event_id, 

135 phase_execution_id=phase_execution_id, 

136 causation_id=causation_id, 

137 correlation_id=correlation_id, 

138 redaction_version=redaction_version, 

139 ) 

140 

141 def append_many( 

142 self, execution_id: str, events: Iterable[tuple[str, dict[str, Any], Actor]] 

143 ) -> builtins.list[StoredEvent]: 

144 """Append ``(event_type, payload, actor)`` events in order, each exactly as 

145 :meth:`append` would (same envelope, sequence and digest chain), in one transaction: 

146 one commit instead of one per event, and all or none of them stored (since 2.0.1).""" 

147 with self._lock, self.connection: 

148 return [ 

149 self._insert(execution_id, event_type, payload, actor=actor) 

150 for event_type, payload, actor in events 

151 ] 

152 

153 def _insert( 

154 self, 

155 execution_id: str, 

156 event_type: str, 

157 payload: dict[str, Any], 

158 *, 

159 actor: Actor = HARNESS_ACTOR, 

160 event_id: str | None = None, 

161 phase_execution_id: str | None = None, 

162 causation_id: str | None = None, 

163 correlation_id: str | None = None, 

164 redaction_version: str = "1", 

165 ) -> StoredEvent: 

166 """One event of the chain; the caller holds the lock and the transaction.""" 

167 from governed_harness.domain.ids import new_id 

168 

169 event_id = event_id or new_id("evt") 

170 occurred_at = datetime.now(UTC).isoformat() 

171 actor_payload = actor.model_dump(mode="json", by_alias=True) 

172 row = self.connection.execute( 

173 "SELECT execution_sequence,event_digest FROM events WHERE execution_id=? " 

174 "ORDER BY execution_sequence DESC LIMIT 1", 

175 (execution_id,), 

176 ).fetchone() 

177 sequence = int(row["execution_sequence"]) + 1 if row else 1 

178 previous = row["event_digest"] if row else None 

179 envelope = { 

180 "schemaVersion": "1.0", 

181 "eventId": event_id, 

182 "executionId": execution_id, 

183 "phaseExecutionId": phase_execution_id, 

184 "causationId": causation_id, 

185 "correlationId": correlation_id, 

186 "sequence": sequence, 

187 "eventType": event_type, 

188 "occurredAt": occurred_at, 

189 "actor": actor_payload, 

190 "payload": payload, 

191 "previousEventDigest": previous, 

192 "redactionVersion": redaction_version, 

193 } 

194 digest = sha256_json(envelope) 

195 self.connection.execute( 

196 """ 

197 INSERT INTO events( 

198 event_id,execution_id,execution_sequence,event_type,occurred_at, 

199 actor_json,payload_json,phase_execution_id,causation_id,correlation_id, 

200 previous_digest,event_digest,redaction_version 

201 ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?) 

202 """, 

203 ( 

204 event_id, 

205 execution_id, 

206 sequence, 

207 event_type, 

208 occurred_at, 

209 json.dumps(actor_payload, sort_keys=True), 

210 json.dumps(payload, sort_keys=True, default=str), 

211 phase_execution_id, 

212 causation_id, 

213 correlation_id, 

214 previous, 

215 digest, 

216 redaction_version, 

217 ), 

218 ) 

219 return StoredEvent( 

220 event_id, 

221 sequence, 

222 execution_id, 

223 event_type, 

224 occurred_at, 

225 actor_payload, 

226 payload, 

227 previous, 

228 digest, 

229 phase_execution_id, 

230 causation_id, 

231 correlation_id, 

232 redaction_version, 

233 ) 

234 

235 def list(self, execution_id: str) -> list[StoredEvent]: 

236 rows = self.connection.execute( 

237 "SELECT * FROM events WHERE execution_id=? ORDER BY execution_sequence", 

238 (execution_id,), 

239 ).fetchall() 

240 return [self._from_row(row) for row in rows] 

241 

242 def list_all(self, *, limit: int | None = None) -> builtins.list[StoredEvent]: 

243 query = "SELECT * FROM events ORDER BY global_sequence" 

244 params: tuple[Any, ...] = () 

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

246 query += " LIMIT ?" 

247 params = (limit,) 

248 return [self._from_row(row) for row in self.connection.execute(query, params).fetchall()] 

249 

250 def execution_ids(self) -> builtins.list[str]: 

251 """Every run that has events, in the order of its first event.""" 

252 rows = self.connection.execute( 

253 "SELECT execution_id FROM events GROUP BY execution_id ORDER BY MIN(global_sequence)" 

254 ).fetchall() 

255 return [str(row["execution_id"]) for row in rows] 

256 

257 def delete_execution(self, execution_id: str) -> int: 

258 """Delete every event of a run (``retention.eventDays``); returns how many.""" 

259 with self._lock, self.connection: 

260 cursor = self.connection.execute( 

261 "DELETE FROM events WHERE execution_id=?", (execution_id,) 

262 ) 

263 return int(cursor.rowcount) 

264 

265 def count(self, execution_id: str | None = None) -> int: 

266 if execution_id is None: 

267 row = self.connection.execute("SELECT COUNT(*) AS count FROM events").fetchone() 

268 else: 

269 row = self.connection.execute( 

270 "SELECT COUNT(*) AS count FROM events WHERE execution_id=?", (execution_id,) 

271 ).fetchone() 

272 return int(row["count"]) 

273 

274 def verify_chain(self, execution_id: str) -> bool: 

275 """``True`` when the chain of the run is intact; raises :class:`EventChainError` at the 

276 first broken link. :meth:`check_chain` reports the same check without raising.""" 

277 check = self.check_chain(execution_id) 

278 if not check.valid: 

279 raise EventChainError(check.error or "event chain is invalid") 

280 return True 

281 

282 def check_chain(self, execution_id: str) -> ChainCheck: 

283 """Walk the chain of a run: sequence without gaps, each event linked to the digest of the 

284 one before it and each digest recomputed from its envelope. A malformed row (a payload 

285 that is not JSON) is a broken link, not an exception.""" 

286 previous: str | None = None 

287 expected_sequence = 1 

288 try: 

289 events = self.list(execution_id) 

290 except (ValueError, TypeError) as unreadable: 

291 return ChainCheck(False, 0, None, None, f"unreadable event: {unreadable}") 

292 for event in events: 

293 error: str | None = None 

294 if event.sequence != expected_sequence: 294 ↛ 295line 294 didn't jump to line 295 because the condition on line 294 was never true

295 error = f"event sequence gap: expected {expected_sequence}, got {event.sequence}" 

296 elif event.previous_digest != previous: 296 ↛ 297line 296 didn't jump to line 297 because the condition on line 296 was never true

297 error = f"previous digest mismatch at event {event.event_id}" 

298 else: 

299 envelope = event.as_dict() 

300 envelope.pop("eventDigest") 

301 if sha256_json(envelope) != event.event_digest: 

302 error = f"event digest mismatch at event {event.event_id}" 

303 if error is not None: 

304 return ChainCheck( 

305 False, len(events), previous, expected_sequence - 1 or None, error 

306 ) 

307 previous = event.event_digest 

308 expected_sequence += 1 

309 return ChainCheck(True, len(events), previous, (expected_sequence - 1) or None, None) 

310 

311 def export_jsonl(self, execution_id: str) -> bytes: 

312 return ( 

313 "\n".join( 

314 json.dumps(event.as_dict(), sort_keys=True, ensure_ascii=False) 

315 for event in self.list(execution_id) 

316 ) 

317 + "\n" 

318 ).encode("utf-8") 

319 

320 def close(self) -> None: 

321 self.connection.close() 

322 

323 def __enter__(self) -> Self: 

324 return self 

325 

326 def __exit__( 

327 self, 

328 exc_type: type[BaseException] | None, 

329 exc: BaseException | None, 

330 traceback: TracebackType | None, 

331 ) -> None: 

332 self.close() 

333 

334 @staticmethod 

335 def _from_row(row: sqlite3.Row) -> StoredEvent: 

336 # The columns by name, as a plain mapping (sqlite3.Row reads the same values by key). 

337 fields = dict(row) 

338 return StoredEvent( 

339 event_id=fields["event_id"], 

340 sequence=fields["execution_sequence"], 

341 execution_id=fields["execution_id"], 

342 event_type=fields["event_type"], 

343 occurred_at=fields["occurred_at"], 

344 actor=json.loads(fields["actor_json"]), 

345 payload=json.loads(fields["payload_json"]), 

346 previous_digest=fields["previous_digest"], 

347 event_digest=fields["event_digest"], 

348 phase_execution_id=fields["phase_execution_id"], 

349 causation_id=fields["causation_id"], 

350 correlation_id=fields["correlation_id"], 

351 redaction_version=fields["redaction_version"], 

352 )