nlp-refinement-cli 0.9.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nlp_refinement/__init__.py +1 -0
- nlp_refinement/diagnostic_doe_support.py +84 -0
- nlp_refinement/doe_receipt_retention.py +81 -0
- nlp_refinement/format_contracts.py +157 -0
- nlp_refinement/host_client.py +505 -0
- nlp_refinement/host_diagnostics.py +430 -0
- nlp_refinement/host_execution_request.py +15 -0
- nlp_refinement/host_executor.py +104 -0
- nlp_refinement/host_refine.py +82 -0
- nlp_refinement/m8_doe_fixtures.py +28 -0
- nlp_refinement/m8_review_coordinator.py +370 -0
- nlp_refinement/patch_proposal_adapter.py +303 -0
- nlp_refinement/refine.py +372 -0
- nlp_refinement/repair_feasibility.py +327 -0
- nlp_refinement/resources/__init__.py +0 -0
- nlp_refinement/resources/prompts/patch-proposal-phase.v5.md +51 -0
- nlp_refinement/resources/prompts/review-phase.v5.md +57 -0
- nlp_refinement/resources/schemas/v5/acceptance-trace.schema.json +17 -0
- nlp_refinement/resources/schemas/v5/artifact.schema.json +17 -0
- nlp_refinement/resources/schemas/v5/finding.schema.json +27 -0
- nlp_refinement/resources/schemas/v5/patch-proposal-result.schema.json +66 -0
- nlp_refinement/resources/schemas/v5/phase-envelope.schema.json +18 -0
- nlp_refinement/resources/schemas/v5/retention-policy.schema.json +16 -0
- nlp_refinement/resources/schemas/v5/review-result.schema.json +37 -0
- nlp_refinement/resources/schemas/v5/run.schema.json +22 -0
- nlp_refinement/review_adapter.py +203 -0
- nlp_refinement/sensitive_data.py +98 -0
- nlp_refinement/state_store.py +1025 -0
- nlp_refinement_cli-0.9.0.dist-info/METADATA +300 -0
- nlp_refinement_cli-0.9.0.dist-info/RECORD +35 -0
- nlp_refinement_cli-0.9.0.dist-info/WHEEL +5 -0
- nlp_refinement_cli-0.9.0.dist-info/entry_points.txt +4 -0
- nlp_refinement_cli-0.9.0.dist-info/licenses/LICENSE +201 -0
- nlp_refinement_cli-0.9.0.dist-info/licenses/NOTICE +4 -0
- nlp_refinement_cli-0.9.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,1025 @@
|
|
|
1
|
+
"""Transactional, local-only state storage for formal refinement runs."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import re
|
|
8
|
+
import secrets
|
|
9
|
+
import sqlite3
|
|
10
|
+
import stat
|
|
11
|
+
from contextlib import contextmanager
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import Any, Iterator
|
|
14
|
+
|
|
15
|
+
from nlp_refinement.sensitive_data import likely_secret_kind
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class StateStoreError(RuntimeError):
|
|
19
|
+
"""Base class for durable-local StateStore failures."""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class LeaseConflict(StateStoreError):
|
|
23
|
+
"""Raised when another active owner holds a run lease."""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class LeaseInvalid(StateStoreError):
|
|
27
|
+
"""Raised when a write lacks a matching, unexpired lease token."""
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class RevisionConflict(StateStoreError):
|
|
31
|
+
"""Raised when a write was prepared from a stale run revision."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class ImmutableFieldError(StateStoreError):
|
|
35
|
+
"""Raised when a finding tries to alter an immutable identity field."""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class InvalidTransition(StateStoreError):
|
|
39
|
+
"""Raised when a requested state transition is not in the M0 state graph."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class RetentionPlanStale(StateStoreError):
|
|
43
|
+
"""Raised when a confirmation does not match the current retention plan."""
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class SensitiveArtifactError(StateStoreError):
|
|
47
|
+
"""Raised when a narrow secret guard blocks durable caller content."""
|
|
48
|
+
|
|
49
|
+
DAY_SECONDS = 24 * 60 * 60
|
|
50
|
+
STALE_AFTER_DAYS = 14
|
|
51
|
+
HOT_ARTIFACT_DAYS = 30
|
|
52
|
+
|
|
53
|
+
TERMINAL_OUTCOMES = {
|
|
54
|
+
"PASS",
|
|
55
|
+
"PASS_WITH_ACCEPTED_RISK",
|
|
56
|
+
"NEEDS_USER_DECISION",
|
|
57
|
+
"NO_MATERIAL_DELTA",
|
|
58
|
+
"SNAPSHOT_STALE",
|
|
59
|
+
"BLOCKED",
|
|
60
|
+
"CANCELLED",
|
|
61
|
+
"STALE",
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
FINAL_STATES = {
|
|
65
|
+
"PASS",
|
|
66
|
+
"PASS_WITH_ACCEPTED_RISK",
|
|
67
|
+
"NO_MATERIAL_DELTA",
|
|
68
|
+
"SNAPSHOT_STALE",
|
|
69
|
+
"CANCELLED",
|
|
70
|
+
"STALE",
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
ARTIFACT_KINDS = {"review", "repair", "verification", "decision", "integrity", "reclassification"}
|
|
74
|
+
ARTIFACT_ACTORS = {"coordinator", "reviewer", "fixer", "verifier", "integrity-gate", "user"}
|
|
75
|
+
REDACTION_STATUSES = {"system-metadata", "caller-attested-redacted"}
|
|
76
|
+
FINDING_SEVERITIES = {"P0", "P1", "P2", "P3"}
|
|
77
|
+
FINDING_GATES = {"blocking", "needs-user-decision", "recordable-risk"}
|
|
78
|
+
FINDING_STATUSES = {"open", "fixed", "verified", "retracted-with-evidence", "accepted-risk"}
|
|
79
|
+
FINDING_SUBJECT_KINDS = {"nl_artifact", "nl_host_boundary"}
|
|
80
|
+
FINDING_EVIDENCE_PLANES = {"static", "runtime", "hybrid"}
|
|
81
|
+
FINDING_EVIDENCE_CONFIDENCE = {"E1-inferred", "E2-direct", "E3-corroborated"}
|
|
82
|
+
FINDING_IMPACT_SCOPES = {
|
|
83
|
+
"single-artifact", "cross-artifact", "core-workflow", "durable-state", "security-boundary",
|
|
84
|
+
}
|
|
85
|
+
FINDING_CLAIM_STATUSES = {"inferred", "direct-static", "observed-runtime", "corroborated"}
|
|
86
|
+
STATIC_ONLY_CATEGORIES = {
|
|
87
|
+
"format_and_encoding",
|
|
88
|
+
"schema_contract",
|
|
89
|
+
"layout_and_discovery",
|
|
90
|
+
"reference_integrity",
|
|
91
|
+
}
|
|
92
|
+
ARTIFACT_CATEGORIES = STATIC_ONLY_CATEGORIES | {
|
|
93
|
+
"semantic_workflow",
|
|
94
|
+
"safety_and_governance",
|
|
95
|
+
"verification_design",
|
|
96
|
+
}
|
|
97
|
+
HOST_BOUNDARY_CATEGORIES = {
|
|
98
|
+
"load_and_discovery",
|
|
99
|
+
"instruction_adherence",
|
|
100
|
+
"state_behavior",
|
|
101
|
+
"outcome_verification",
|
|
102
|
+
"safety_behavior",
|
|
103
|
+
}
|
|
104
|
+
RUN_STATES = {
|
|
105
|
+
"DRAFT", "READY", "REVIEWING", "TRIAGING", "REPAIRING", "VERIFYING",
|
|
106
|
+
"REREVIEWING", "INTEGRITY_CHECK", "ROLLING_BACK", "SNAPSHOT_STALE",
|
|
107
|
+
"STALE", "PASS", "PASS_WITH_ACCEPTED_RISK", "NEEDS_USER_DECISION",
|
|
108
|
+
"NO_MATERIAL_DELTA", "BLOCKED", "CANCELLED",
|
|
109
|
+
}
|
|
110
|
+
RUN_OUTCOMES = {"IN_PROGRESS"} | TERMINAL_OUTCOMES
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def validate_finding_classification(subject_kind: str, evidence_plane: str, category: str) -> None:
|
|
114
|
+
"""Validate the v5 NL-review taxonomy without accepting support-code findings."""
|
|
115
|
+
if subject_kind not in FINDING_SUBJECT_KINDS:
|
|
116
|
+
raise ValueError("finding subject_kind is invalid")
|
|
117
|
+
if evidence_plane not in FINDING_EVIDENCE_PLANES:
|
|
118
|
+
raise ValueError("finding evidence_plane is invalid")
|
|
119
|
+
if subject_kind == "nl_artifact":
|
|
120
|
+
if category not in ARTIFACT_CATEGORIES:
|
|
121
|
+
raise ValueError("finding category is invalid for nl_artifact")
|
|
122
|
+
if category in STATIC_ONLY_CATEGORIES and evidence_plane != "static":
|
|
123
|
+
raise ValueError("static NL artifact category requires static evidence")
|
|
124
|
+
if category not in STATIC_ONLY_CATEGORIES and evidence_plane not in {"static", "hybrid"}:
|
|
125
|
+
raise ValueError("NL artifact semantic category requires static or hybrid evidence")
|
|
126
|
+
return
|
|
127
|
+
if category not in HOST_BOUNDARY_CATEGORIES:
|
|
128
|
+
raise ValueError("finding category is invalid for nl_host_boundary")
|
|
129
|
+
if evidence_plane not in {"runtime", "hybrid"}:
|
|
130
|
+
raise ValueError("nl_host_boundary category requires runtime or hybrid evidence")
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def validate_finding_assessment(
|
|
134
|
+
severity: str,
|
|
135
|
+
effective_gate: str,
|
|
136
|
+
evidence_plane: str,
|
|
137
|
+
evidence_confidence: str,
|
|
138
|
+
impact_scope: str,
|
|
139
|
+
claim_status: str,
|
|
140
|
+
) -> None:
|
|
141
|
+
"""Keep impact severity, evidence confidence, and workflow gate independent but coherent."""
|
|
142
|
+
if evidence_confidence not in FINDING_EVIDENCE_CONFIDENCE:
|
|
143
|
+
raise ValueError("finding evidence_confidence is invalid")
|
|
144
|
+
if impact_scope not in FINDING_IMPACT_SCOPES:
|
|
145
|
+
raise ValueError("finding impact_scope is invalid")
|
|
146
|
+
if claim_status not in FINDING_CLAIM_STATUSES:
|
|
147
|
+
raise ValueError("finding claim_status is invalid")
|
|
148
|
+
if evidence_confidence == "E1-inferred" and claim_status != "inferred":
|
|
149
|
+
raise ValueError("E1-inferred evidence requires inferred claim_status")
|
|
150
|
+
if evidence_confidence == "E2-direct":
|
|
151
|
+
if claim_status == "direct-static" and evidence_plane not in {"static", "hybrid"}:
|
|
152
|
+
raise ValueError("direct-static claim_status requires static or hybrid evidence")
|
|
153
|
+
if claim_status == "observed-runtime" and evidence_plane not in {"runtime", "hybrid"}:
|
|
154
|
+
raise ValueError("observed-runtime claim_status requires runtime or hybrid evidence")
|
|
155
|
+
if claim_status not in {"direct-static", "observed-runtime"}:
|
|
156
|
+
raise ValueError("E2-direct evidence requires a direct-static or observed-runtime claim_status")
|
|
157
|
+
if evidence_confidence == "E3-corroborated" and (
|
|
158
|
+
claim_status != "corroborated" or evidence_plane != "hybrid"
|
|
159
|
+
):
|
|
160
|
+
raise ValueError("E3-corroborated evidence requires corroborated claim_status and hybrid evidence")
|
|
161
|
+
if severity == "P0":
|
|
162
|
+
if effective_gate != "blocking":
|
|
163
|
+
raise ValueError("P0 requires blocking gate")
|
|
164
|
+
if evidence_confidence == "E1-inferred":
|
|
165
|
+
raise ValueError("P0 requires direct or corroborated evidence")
|
|
166
|
+
elif severity == "P1":
|
|
167
|
+
if effective_gate == "recordable-risk":
|
|
168
|
+
raise ValueError("P1 cannot use recordable-risk gate")
|
|
169
|
+
elif severity == "P2":
|
|
170
|
+
if effective_gate == "blocking":
|
|
171
|
+
raise ValueError("P2 cannot use blocking gate")
|
|
172
|
+
elif severity == "P3":
|
|
173
|
+
if effective_gate != "recordable-risk":
|
|
174
|
+
raise ValueError("P3 requires recordable-risk gate")
|
|
175
|
+
|
|
176
|
+
ALLOWED_TRANSITIONS = {
|
|
177
|
+
"DRAFT": {"READY"},
|
|
178
|
+
"READY": {"REVIEWING"},
|
|
179
|
+
"REVIEWING": {"TRIAGING"},
|
|
180
|
+
"TRIAGING": {"REPAIRING", "NEEDS_USER_DECISION"},
|
|
181
|
+
"REPAIRING": {"VERIFYING"},
|
|
182
|
+
"VERIFYING": {"REREVIEWING", "ROLLING_BACK"},
|
|
183
|
+
"REREVIEWING": {"INTEGRITY_CHECK"},
|
|
184
|
+
"INTEGRITY_CHECK": {"PASS", "PASS_WITH_ACCEPTED_RISK", "NO_MATERIAL_DELTA", "NEEDS_USER_DECISION"},
|
|
185
|
+
"ROLLING_BACK": {"REVIEWING"},
|
|
186
|
+
"NEEDS_USER_DECISION": {"TRIAGING"},
|
|
187
|
+
"BLOCKED": {"READY"},
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
class StateStore:
|
|
192
|
+
"""Own local durable state; target-worktree writes remain outside this class."""
|
|
193
|
+
|
|
194
|
+
def __init__(self, database_path: Path | str) -> None:
|
|
195
|
+
self.database_path = Path(database_path)
|
|
196
|
+
|
|
197
|
+
def initialize(self) -> None:
|
|
198
|
+
state_root = self.database_path.parent
|
|
199
|
+
if state_root.exists():
|
|
200
|
+
if not state_root.is_dir():
|
|
201
|
+
raise ValueError("database parent must be a directory")
|
|
202
|
+
if stat.S_IMODE(state_root.stat().st_mode) & 0o077:
|
|
203
|
+
raise PermissionError("database directory must be owner-only")
|
|
204
|
+
else:
|
|
205
|
+
state_root.mkdir(parents=True, mode=0o700)
|
|
206
|
+
if self.database_path.exists():
|
|
207
|
+
if not self.database_path.is_file():
|
|
208
|
+
raise ValueError("database path must be a regular file")
|
|
209
|
+
if stat.S_IMODE(self.database_path.stat().st_mode) & 0o077:
|
|
210
|
+
raise PermissionError("database file must be owner-only")
|
|
211
|
+
with self._connection() as connection:
|
|
212
|
+
tables = {
|
|
213
|
+
row["name"]
|
|
214
|
+
for row in connection.execute(
|
|
215
|
+
"SELECT name FROM sqlite_master WHERE type = 'table'"
|
|
216
|
+
)
|
|
217
|
+
}
|
|
218
|
+
if "archived_runs" in tables:
|
|
219
|
+
raise StateStoreError(
|
|
220
|
+
"legacy ledger data uses the retired archive table; export or remove it explicitly"
|
|
221
|
+
)
|
|
222
|
+
if "runs" in tables:
|
|
223
|
+
for row in connection.execute("SELECT run_id, run_json FROM runs"):
|
|
224
|
+
try:
|
|
225
|
+
version = json.loads(row["run_json"]).get("schema_version")
|
|
226
|
+
except json.JSONDecodeError as error:
|
|
227
|
+
raise StateStoreError("stored run JSON is invalid") from error
|
|
228
|
+
if version != "5.0":
|
|
229
|
+
raise StateStoreError(
|
|
230
|
+
f"legacy ledger data for {row['run_id']} is unsupported; export or remove it explicitly"
|
|
231
|
+
)
|
|
232
|
+
connection.execute("PRAGMA journal_mode = WAL")
|
|
233
|
+
connection.execute("PRAGMA foreign_keys = ON")
|
|
234
|
+
connection.executescript(
|
|
235
|
+
"""
|
|
236
|
+
CREATE TABLE IF NOT EXISTS runs (
|
|
237
|
+
run_id TEXT PRIMARY KEY,
|
|
238
|
+
project_key TEXT NOT NULL,
|
|
239
|
+
target_snapshot_hash TEXT NOT NULL,
|
|
240
|
+
current_snapshot_hash TEXT NOT NULL,
|
|
241
|
+
state TEXT NOT NULL,
|
|
242
|
+
outcome TEXT NOT NULL,
|
|
243
|
+
revision INTEGER NOT NULL,
|
|
244
|
+
run_json TEXT NOT NULL,
|
|
245
|
+
immutable_anchor_json TEXT NOT NULL,
|
|
246
|
+
created_at INTEGER NOT NULL,
|
|
247
|
+
updated_at INTEGER NOT NULL
|
|
248
|
+
);
|
|
249
|
+
CREATE TABLE IF NOT EXISTS leases (
|
|
250
|
+
run_id TEXT PRIMARY KEY REFERENCES runs(run_id) ON DELETE CASCADE,
|
|
251
|
+
owner_session_id TEXT NOT NULL,
|
|
252
|
+
token_digest TEXT NOT NULL,
|
|
253
|
+
expires_at INTEGER NOT NULL,
|
|
254
|
+
heartbeat_at INTEGER NOT NULL
|
|
255
|
+
);
|
|
256
|
+
CREATE TABLE IF NOT EXISTS artifacts (
|
|
257
|
+
sequence INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
258
|
+
artifact_id TEXT UNIQUE,
|
|
259
|
+
run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
|
|
260
|
+
kind TEXT NOT NULL,
|
|
261
|
+
actor TEXT NOT NULL,
|
|
262
|
+
input_artifact_refs_json TEXT NOT NULL,
|
|
263
|
+
content_hash TEXT NOT NULL,
|
|
264
|
+
body TEXT NOT NULL,
|
|
265
|
+
redaction_status TEXT NOT NULL,
|
|
266
|
+
revision INTEGER NOT NULL,
|
|
267
|
+
created_at INTEGER NOT NULL
|
|
268
|
+
);
|
|
269
|
+
CREATE TABLE IF NOT EXISTS findings (
|
|
270
|
+
run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
|
|
271
|
+
finding_id TEXT NOT NULL,
|
|
272
|
+
fingerprint TEXT NOT NULL,
|
|
273
|
+
origin_severity TEXT NOT NULL,
|
|
274
|
+
finding_json TEXT NOT NULL,
|
|
275
|
+
created_at INTEGER NOT NULL,
|
|
276
|
+
updated_at INTEGER NOT NULL,
|
|
277
|
+
PRIMARY KEY (run_id, finding_id),
|
|
278
|
+
UNIQUE (run_id, fingerprint)
|
|
279
|
+
);
|
|
280
|
+
CREATE TABLE IF NOT EXISTS events (
|
|
281
|
+
sequence INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
282
|
+
run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
|
|
283
|
+
revision INTEGER NOT NULL,
|
|
284
|
+
event_type TEXT NOT NULL,
|
|
285
|
+
payload_json TEXT NOT NULL,
|
|
286
|
+
created_at INTEGER NOT NULL
|
|
287
|
+
);
|
|
288
|
+
"""
|
|
289
|
+
)
|
|
290
|
+
if not self.database_path.exists():
|
|
291
|
+
raise RuntimeError("SQLite did not create the database file")
|
|
292
|
+
self.database_path.chmod(0o600)
|
|
293
|
+
|
|
294
|
+
def create_run(self, run: dict[str, Any], immutable_anchor: dict[str, Any], now: int) -> dict[str, Any]:
|
|
295
|
+
self._validate_new_run(run)
|
|
296
|
+
with self._transaction() as connection:
|
|
297
|
+
connection.execute(
|
|
298
|
+
"""
|
|
299
|
+
INSERT INTO runs (
|
|
300
|
+
run_id, project_key, target_snapshot_hash, current_snapshot_hash,
|
|
301
|
+
state, outcome, revision, run_json, immutable_anchor_json,
|
|
302
|
+
created_at, updated_at
|
|
303
|
+
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
304
|
+
""",
|
|
305
|
+
(
|
|
306
|
+
run["run_id"],
|
|
307
|
+
run["project_key"],
|
|
308
|
+
run["target_snapshot_hash"],
|
|
309
|
+
run["current_snapshot_hash"],
|
|
310
|
+
run["state"],
|
|
311
|
+
run["outcome"],
|
|
312
|
+
run["revision"],
|
|
313
|
+
self._dump(run),
|
|
314
|
+
self._dump(immutable_anchor),
|
|
315
|
+
now,
|
|
316
|
+
now,
|
|
317
|
+
),
|
|
318
|
+
)
|
|
319
|
+
self._record_event(connection, run["run_id"], 0, "run-created", {"immutable_anchor_hash": self._digest(self._dump(immutable_anchor))}, now)
|
|
320
|
+
return self.get_run(str(run["run_id"]))
|
|
321
|
+
|
|
322
|
+
def get_run(self, run_id: str) -> dict[str, Any]:
|
|
323
|
+
with self._connection() as connection:
|
|
324
|
+
row = connection.execute("SELECT * FROM runs WHERE run_id = ?", (run_id,)).fetchone()
|
|
325
|
+
if row is None:
|
|
326
|
+
raise KeyError(f"run not found: {run_id}")
|
|
327
|
+
return self._run_from_row(row)
|
|
328
|
+
|
|
329
|
+
def acquire_lease(self, run_id: str, owner_session_id: str, now: int, ttl_seconds: int = 600) -> dict[str, Any]:
|
|
330
|
+
if ttl_seconds <= 0:
|
|
331
|
+
raise ValueError("ttl_seconds must be positive")
|
|
332
|
+
token = secrets.token_urlsafe(32)
|
|
333
|
+
digest = self._digest(token)
|
|
334
|
+
expires_at = now + ttl_seconds
|
|
335
|
+
with self._transaction() as connection:
|
|
336
|
+
self._require_run(connection, run_id)
|
|
337
|
+
current = connection.execute("SELECT * FROM leases WHERE run_id = ?", (run_id,)).fetchone()
|
|
338
|
+
if current is not None and current["expires_at"] > now:
|
|
339
|
+
raise LeaseConflict(f"run {run_id} is leased by {current['owner_session_id']}")
|
|
340
|
+
connection.execute(
|
|
341
|
+
"""
|
|
342
|
+
INSERT INTO leases (run_id, owner_session_id, token_digest, expires_at, heartbeat_at)
|
|
343
|
+
VALUES (?, ?, ?, ?, ?)
|
|
344
|
+
ON CONFLICT(run_id) DO UPDATE SET
|
|
345
|
+
owner_session_id = excluded.owner_session_id,
|
|
346
|
+
token_digest = excluded.token_digest,
|
|
347
|
+
expires_at = excluded.expires_at,
|
|
348
|
+
heartbeat_at = excluded.heartbeat_at
|
|
349
|
+
""",
|
|
350
|
+
(run_id, owner_session_id, digest, expires_at, now),
|
|
351
|
+
)
|
|
352
|
+
self._record_event(connection, run_id, self._run_revision(connection, run_id), "lease-acquired", {"owner_session_id": owner_session_id, "expires_at": expires_at}, now)
|
|
353
|
+
return {"run_id": run_id, "owner_session_id": owner_session_id, "token": token, "expires_at": expires_at}
|
|
354
|
+
|
|
355
|
+
def renew_lease(self, run_id: str, lease_token: str, now: int, ttl_seconds: int = 600) -> dict[str, Any]:
|
|
356
|
+
with self._transaction() as connection:
|
|
357
|
+
lease = self._require_lease(connection, run_id, lease_token, now)
|
|
358
|
+
expires_at = now + ttl_seconds
|
|
359
|
+
connection.execute("UPDATE leases SET expires_at = ?, heartbeat_at = ? WHERE run_id = ?", (expires_at, now, run_id))
|
|
360
|
+
self._record_event(connection, run_id, self._run_revision(connection, run_id), "lease-renewed", {"owner_session_id": lease["owner_session_id"], "expires_at": expires_at}, now)
|
|
361
|
+
return {"run_id": run_id, "owner_session_id": lease["owner_session_id"], "token": lease_token, "expires_at": expires_at}
|
|
362
|
+
|
|
363
|
+
def release_lease(self, run_id: str, lease_token: str, now: int) -> None:
|
|
364
|
+
"""Release a matching lease so a subsequent local session can continue immediately."""
|
|
365
|
+
with self._transaction() as connection:
|
|
366
|
+
lease = self._require_lease(connection, run_id, lease_token, now)
|
|
367
|
+
connection.execute("DELETE FROM leases WHERE run_id = ?", (run_id,))
|
|
368
|
+
self._record_event(
|
|
369
|
+
connection,
|
|
370
|
+
run_id,
|
|
371
|
+
self._run_revision(connection, run_id),
|
|
372
|
+
"lease-released",
|
|
373
|
+
{"owner_session_id": lease["owner_session_id"]},
|
|
374
|
+
now,
|
|
375
|
+
)
|
|
376
|
+
|
|
377
|
+
def append_artifact(
|
|
378
|
+
self,
|
|
379
|
+
run_id: str,
|
|
380
|
+
expected_revision: int,
|
|
381
|
+
lease_token: str,
|
|
382
|
+
kind: str,
|
|
383
|
+
actor: str,
|
|
384
|
+
body: str,
|
|
385
|
+
input_artifact_refs: list[str] | None = None,
|
|
386
|
+
redaction_status: str = "caller-attested-redacted",
|
|
387
|
+
now: int = 0,
|
|
388
|
+
) -> dict[str, Any]:
|
|
389
|
+
if not body:
|
|
390
|
+
raise ValueError("artifact body must not be empty")
|
|
391
|
+
if kind not in ARTIFACT_KINDS:
|
|
392
|
+
raise ValueError(f"unsupported artifact kind: {kind}")
|
|
393
|
+
if actor not in ARTIFACT_ACTORS:
|
|
394
|
+
raise ValueError(f"unsupported artifact actor: {actor}")
|
|
395
|
+
if redaction_status not in REDACTION_STATUSES:
|
|
396
|
+
raise ValueError("artifacts with rejected-sensitive status must not be persisted")
|
|
397
|
+
if redaction_status == "system-metadata" and (kind != "integrity" or actor not in {"coordinator", "integrity-gate"}):
|
|
398
|
+
raise ValueError("system-metadata is reserved for coordinator integrity receipts")
|
|
399
|
+
self._require_no_likely_secret(body, redaction_status)
|
|
400
|
+
refs = input_artifact_refs or []
|
|
401
|
+
with self._transaction() as connection:
|
|
402
|
+
run = self._require_run(connection, run_id)
|
|
403
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
404
|
+
self._require_revision(run, expected_revision)
|
|
405
|
+
self._require_artifact_refs(connection, run_id, refs)
|
|
406
|
+
cursor = connection.execute(
|
|
407
|
+
"""
|
|
408
|
+
INSERT INTO artifacts (
|
|
409
|
+
artifact_id, run_id, kind, actor, input_artifact_refs_json,
|
|
410
|
+
content_hash, body, redaction_status, revision, created_at
|
|
411
|
+
) VALUES (NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
412
|
+
""",
|
|
413
|
+
(run_id, kind, actor, self._dump(refs), self._digest(body), body, redaction_status, expected_revision + 1, now),
|
|
414
|
+
)
|
|
415
|
+
sequence = int(cursor.lastrowid)
|
|
416
|
+
artifact_id = f"r{sequence:08d}-{kind}"
|
|
417
|
+
connection.execute("UPDATE artifacts SET artifact_id = ? WHERE sequence = ?", (artifact_id, sequence))
|
|
418
|
+
updated = self._advance_run(connection, run, now)
|
|
419
|
+
self._record_event(connection, run_id, updated["revision"], "artifact-appended", {"artifact_id": artifact_id, "kind": kind, "actor": actor}, now)
|
|
420
|
+
return {"artifact_id": artifact_id, "revision": updated["revision"], "content_hash": self._digest(body), "kind": kind, "actor": actor}
|
|
421
|
+
|
|
422
|
+
def record_finding(self, run_id: str, expected_revision: int, lease_token: str, finding: dict[str, Any], now: int) -> dict[str, Any]:
|
|
423
|
+
with self._transaction() as connection:
|
|
424
|
+
run = self._require_run(connection, run_id)
|
|
425
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
426
|
+
self._require_revision(run, expected_revision)
|
|
427
|
+
self._validate_finding_identity(run_id, finding)
|
|
428
|
+
self._require_artifact_refs(connection, run_id, list(finding["evidence_refs"]))
|
|
429
|
+
self._require_accepted_risk_decision(connection, run_id, finding)
|
|
430
|
+
connection.execute(
|
|
431
|
+
"""
|
|
432
|
+
INSERT INTO findings (run_id, finding_id, fingerprint, origin_severity, finding_json, created_at, updated_at)
|
|
433
|
+
VALUES (?, ?, ?, ?, ?, ?, ?)
|
|
434
|
+
""",
|
|
435
|
+
(run_id, finding["finding_id"], finding["fingerprint"], finding["origin_severity"], self._dump(finding), now, now),
|
|
436
|
+
)
|
|
437
|
+
updated = self._advance_run(connection, run, now)
|
|
438
|
+
self._record_event(connection, run_id, updated["revision"], "finding-recorded", {"finding_id": finding["finding_id"]}, now)
|
|
439
|
+
return {"finding_id": finding["finding_id"], "revision": updated["revision"]}
|
|
440
|
+
|
|
441
|
+
def update_finding(self, run_id: str, expected_revision: int, lease_token: str, finding: dict[str, Any], now: int) -> dict[str, Any]:
|
|
442
|
+
with self._transaction() as connection:
|
|
443
|
+
run = self._require_run(connection, run_id)
|
|
444
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
445
|
+
self._require_revision(run, expected_revision)
|
|
446
|
+
self._validate_finding_identity(run_id, finding)
|
|
447
|
+
existing = connection.execute("SELECT * FROM findings WHERE run_id = ? AND finding_id = ?", (run_id, finding["finding_id"])).fetchone()
|
|
448
|
+
if existing is None:
|
|
449
|
+
raise KeyError(f"finding not found: {finding['finding_id']}")
|
|
450
|
+
existing_finding = json.loads(existing["finding_json"])
|
|
451
|
+
if (
|
|
452
|
+
finding["origin_severity"] != existing["origin_severity"]
|
|
453
|
+
or finding["fingerprint"] != existing["fingerprint"]
|
|
454
|
+
or finding["effective_gate"] != existing_finding["effective_gate"]
|
|
455
|
+
or any(
|
|
456
|
+
finding[field] != existing_finding[field]
|
|
457
|
+
for field in (
|
|
458
|
+
"subject_kind", "evidence_plane", "category",
|
|
459
|
+
"evidence_confidence", "impact_scope", "claim_status",
|
|
460
|
+
)
|
|
461
|
+
)
|
|
462
|
+
):
|
|
463
|
+
raise ImmutableFieldError("finding identity and classification fields cannot change")
|
|
464
|
+
self._require_artifact_refs(connection, run_id, list(finding["evidence_refs"]))
|
|
465
|
+
self._require_accepted_risk_decision(connection, run_id, finding)
|
|
466
|
+
connection.execute("UPDATE findings SET finding_json = ?, updated_at = ? WHERE run_id = ? AND finding_id = ?", (self._dump(finding), now, run_id, finding["finding_id"]))
|
|
467
|
+
updated = self._advance_run(connection, run, now)
|
|
468
|
+
self._record_event(connection, run_id, updated["revision"], "finding-updated", {"finding_id": finding["finding_id"]}, now)
|
|
469
|
+
return {"finding_id": finding["finding_id"], "revision": updated["revision"]}
|
|
470
|
+
|
|
471
|
+
def apply_review_phase(
|
|
472
|
+
self,
|
|
473
|
+
run_id: str,
|
|
474
|
+
expected_revision: int,
|
|
475
|
+
lease_token: str,
|
|
476
|
+
observed_snapshot_hash: str,
|
|
477
|
+
review_body: str,
|
|
478
|
+
redaction_status: str,
|
|
479
|
+
planned_findings: list[dict[str, Any]],
|
|
480
|
+
now: int,
|
|
481
|
+
) -> dict[str, Any]:
|
|
482
|
+
"""Atomically persist one externally produced review and its findings.
|
|
483
|
+
|
|
484
|
+
`planned_findings` contains coordinator-validated dictionaries with
|
|
485
|
+
action `new` or `duplicate`; the review artifact evidence reference is
|
|
486
|
+
allocated inside this transaction rather than supplied by the reviewer.
|
|
487
|
+
"""
|
|
488
|
+
if redaction_status != "caller-attested-redacted":
|
|
489
|
+
raise ValueError("review content requires caller-attested-redacted status")
|
|
490
|
+
if not review_body:
|
|
491
|
+
raise ValueError("review body must not be empty")
|
|
492
|
+
self._require_no_likely_secret(review_body, redaction_status)
|
|
493
|
+
with self._transaction() as connection:
|
|
494
|
+
run = self._require_run(connection, run_id)
|
|
495
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
496
|
+
self._require_revision(run, expected_revision)
|
|
497
|
+
if run["state"] != "READY":
|
|
498
|
+
raise InvalidTransition(f"review requires READY state, found {run['state']}")
|
|
499
|
+
if observed_snapshot_hash != run["current_snapshot_hash"]:
|
|
500
|
+
run["state"] = "SNAPSHOT_STALE"
|
|
501
|
+
run["outcome"] = "SNAPSHOT_STALE"
|
|
502
|
+
run["current_snapshot_hash"] = observed_snapshot_hash
|
|
503
|
+
stale = self._write_run(connection, run, now)
|
|
504
|
+
self._record_event(connection, run_id, stale["revision"], "snapshot-stale", {"observed_snapshot_hash": observed_snapshot_hash}, now)
|
|
505
|
+
return {"run": stale, "artifact_id": None, "new_finding_ids": [], "duplicate_finding_ids": []}
|
|
506
|
+
|
|
507
|
+
run["state"] = "REVIEWING"
|
|
508
|
+
reviewing = self._write_run(connection, run, now)
|
|
509
|
+
self._record_event(connection, run_id, reviewing["revision"], "state-transition", {"state": "REVIEWING", "outcome": "IN_PROGRESS"}, now)
|
|
510
|
+
cursor = connection.execute(
|
|
511
|
+
"""
|
|
512
|
+
INSERT INTO artifacts (
|
|
513
|
+
artifact_id, run_id, kind, actor, input_artifact_refs_json,
|
|
514
|
+
content_hash, body, redaction_status, revision, created_at
|
|
515
|
+
) VALUES (NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
516
|
+
""",
|
|
517
|
+
(run_id, "review", "reviewer", self._dump([]), self._digest(review_body), review_body, redaction_status, reviewing["revision"] + 1, now),
|
|
518
|
+
)
|
|
519
|
+
artifact_id = f"r{int(cursor.lastrowid):08d}-review"
|
|
520
|
+
connection.execute("UPDATE artifacts SET artifact_id = ? WHERE sequence = ?", (artifact_id, cursor.lastrowid))
|
|
521
|
+
current = self._advance_run(connection, reviewing, now)
|
|
522
|
+
self._record_event(connection, run_id, current["revision"], "artifact-appended", {"artifact_id": artifact_id, "kind": "review", "actor": "reviewer"}, now)
|
|
523
|
+
|
|
524
|
+
new_finding_ids: list[str] = []
|
|
525
|
+
duplicate_finding_ids: list[str] = []
|
|
526
|
+
for planned in planned_findings:
|
|
527
|
+
if set(planned) != {"action", "finding"} or planned["action"] not in {"new", "duplicate"}:
|
|
528
|
+
raise ValueError("invalid planned review finding")
|
|
529
|
+
finding = dict(planned["finding"])
|
|
530
|
+
finding["evidence_refs"] = [*finding["evidence_refs"], artifact_id]
|
|
531
|
+
self._validate_finding_identity(run_id, finding)
|
|
532
|
+
if planned["action"] == "new":
|
|
533
|
+
connection.execute(
|
|
534
|
+
"""
|
|
535
|
+
INSERT INTO findings (run_id, finding_id, fingerprint, origin_severity, finding_json, created_at, updated_at)
|
|
536
|
+
VALUES (?, ?, ?, ?, ?, ?, ?)
|
|
537
|
+
""",
|
|
538
|
+
(run_id, finding["finding_id"], finding["fingerprint"], finding["origin_severity"], self._dump(finding), now, now),
|
|
539
|
+
)
|
|
540
|
+
new_finding_ids.append(finding["finding_id"])
|
|
541
|
+
event_type = "finding-recorded"
|
|
542
|
+
else:
|
|
543
|
+
existing = connection.execute(
|
|
544
|
+
"SELECT * FROM findings WHERE run_id = ? AND finding_id = ?", (run_id, finding["finding_id"])
|
|
545
|
+
).fetchone()
|
|
546
|
+
if existing is None:
|
|
547
|
+
raise KeyError(f"finding not found: {finding['finding_id']}")
|
|
548
|
+
existing_finding = json.loads(existing["finding_json"])
|
|
549
|
+
if (
|
|
550
|
+
finding["origin_severity"] != existing["origin_severity"]
|
|
551
|
+
or finding["fingerprint"] != existing["fingerprint"]
|
|
552
|
+
or finding["effective_gate"] != existing_finding["effective_gate"]
|
|
553
|
+
or any(
|
|
554
|
+
finding[field] != existing_finding[field]
|
|
555
|
+
for field in (
|
|
556
|
+
"subject_kind", "evidence_plane", "category",
|
|
557
|
+
"evidence_confidence", "impact_scope", "claim_status",
|
|
558
|
+
)
|
|
559
|
+
)
|
|
560
|
+
):
|
|
561
|
+
raise ImmutableFieldError("finding identity and classification fields cannot change")
|
|
562
|
+
connection.execute(
|
|
563
|
+
"UPDATE findings SET finding_json = ?, updated_at = ? WHERE run_id = ? AND finding_id = ?",
|
|
564
|
+
(self._dump(finding), now, run_id, finding["finding_id"]),
|
|
565
|
+
)
|
|
566
|
+
duplicate_finding_ids.append(finding["finding_id"])
|
|
567
|
+
event_type = "finding-updated"
|
|
568
|
+
current = self._advance_run(connection, current, now)
|
|
569
|
+
self._record_event(connection, run_id, current["revision"], event_type, {"finding_id": finding["finding_id"]}, now)
|
|
570
|
+
|
|
571
|
+
current["state"] = "TRIAGING"
|
|
572
|
+
triaged = self._write_run(connection, current, now)
|
|
573
|
+
self._record_event(connection, run_id, triaged["revision"], "state-transition", {"state": "TRIAGING", "outcome": "IN_PROGRESS"}, now)
|
|
574
|
+
return {
|
|
575
|
+
"run": triaged,
|
|
576
|
+
"artifact_id": artifact_id,
|
|
577
|
+
"new_finding_ids": new_finding_ids,
|
|
578
|
+
"duplicate_finding_ids": duplicate_finding_ids,
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
def record_user_decision(self, run_id: str, expected_revision: int, lease_token: str, body: str, now: int) -> dict[str, Any]:
|
|
582
|
+
return self.append_artifact(
|
|
583
|
+
run_id,
|
|
584
|
+
expected_revision,
|
|
585
|
+
lease_token,
|
|
586
|
+
"decision",
|
|
587
|
+
"user",
|
|
588
|
+
body,
|
|
589
|
+
redaction_status="caller-attested-redacted",
|
|
590
|
+
now=now,
|
|
591
|
+
)
|
|
592
|
+
|
|
593
|
+
def apply_patch_proposal_phase(
|
|
594
|
+
self,
|
|
595
|
+
run_id: str,
|
|
596
|
+
expected_revision: int,
|
|
597
|
+
lease_token: str,
|
|
598
|
+
observed_snapshot_hash: str,
|
|
599
|
+
proposal_body: str,
|
|
600
|
+
redaction_status: str,
|
|
601
|
+
finding_ids: list[str],
|
|
602
|
+
input_artifact_refs: list[str],
|
|
603
|
+
now: int,
|
|
604
|
+
) -> dict[str, Any]:
|
|
605
|
+
"""Atomically record a human-only proposal without touching its target.
|
|
606
|
+
|
|
607
|
+
The proposal remains a review artifact and may only attach evidence to
|
|
608
|
+
currently open findings. A drifted snapshot is terminal and records no
|
|
609
|
+
proposal artifact or finding mutation.
|
|
610
|
+
"""
|
|
611
|
+
if redaction_status != "caller-attested-redacted":
|
|
612
|
+
raise ValueError("patch proposal content requires caller-attested-redacted status")
|
|
613
|
+
if not proposal_body or not finding_ids:
|
|
614
|
+
raise ValueError("patch proposal body and finding IDs must not be empty")
|
|
615
|
+
self._require_no_likely_secret(proposal_body, redaction_status)
|
|
616
|
+
if len(finding_ids) != len(set(finding_ids)):
|
|
617
|
+
raise ValueError("patch proposal finding IDs must be unique")
|
|
618
|
+
with self._transaction() as connection:
|
|
619
|
+
run = self._require_run(connection, run_id)
|
|
620
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
621
|
+
self._require_revision(run, expected_revision)
|
|
622
|
+
if run["state"] != "TRIAGING":
|
|
623
|
+
raise InvalidTransition(f"patch proposal requires TRIAGING state, found {run['state']}")
|
|
624
|
+
if observed_snapshot_hash != run["current_snapshot_hash"]:
|
|
625
|
+
run["state"] = "SNAPSHOT_STALE"
|
|
626
|
+
run["outcome"] = "SNAPSHOT_STALE"
|
|
627
|
+
run["current_snapshot_hash"] = observed_snapshot_hash
|
|
628
|
+
stale = self._write_run(connection, run, now)
|
|
629
|
+
self._record_event(connection, run_id, stale["revision"], "snapshot-stale", {"observed_snapshot_hash": observed_snapshot_hash}, now)
|
|
630
|
+
return {"run": stale, "artifact_id": None, "proposal_count": 0}
|
|
631
|
+
self._require_artifact_refs(connection, run_id, input_artifact_refs)
|
|
632
|
+
findings: list[tuple[str, dict[str, Any]]] = []
|
|
633
|
+
for finding_id in finding_ids:
|
|
634
|
+
row = connection.execute(
|
|
635
|
+
"SELECT finding_json FROM findings WHERE run_id = ? AND finding_id = ?", (run_id, finding_id)
|
|
636
|
+
).fetchone()
|
|
637
|
+
if row is None:
|
|
638
|
+
raise KeyError(f"finding not found: {finding_id}")
|
|
639
|
+
finding = json.loads(row["finding_json"])
|
|
640
|
+
if finding["status"] != "open":
|
|
641
|
+
raise ValueError(f"patch proposal requires an open finding: {finding_id}")
|
|
642
|
+
findings.append((finding_id, finding))
|
|
643
|
+
cursor = connection.execute(
|
|
644
|
+
"""
|
|
645
|
+
INSERT INTO artifacts (
|
|
646
|
+
artifact_id, run_id, kind, actor, input_artifact_refs_json,
|
|
647
|
+
content_hash, body, redaction_status, revision, created_at
|
|
648
|
+
) VALUES (NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
|
649
|
+
""",
|
|
650
|
+
(run_id, "review", "reviewer", self._dump(input_artifact_refs), self._digest(proposal_body), proposal_body, redaction_status, run["revision"] + 1, now),
|
|
651
|
+
)
|
|
652
|
+
artifact_id = f"r{int(cursor.lastrowid):08d}-review"
|
|
653
|
+
connection.execute("UPDATE artifacts SET artifact_id = ? WHERE sequence = ?", (artifact_id, cursor.lastrowid))
|
|
654
|
+
for finding_id, finding in findings:
|
|
655
|
+
finding["evidence_refs"] = [*finding["evidence_refs"], artifact_id]
|
|
656
|
+
connection.execute(
|
|
657
|
+
"UPDATE findings SET finding_json = ?, updated_at = ? WHERE run_id = ? AND finding_id = ?",
|
|
658
|
+
(self._dump(finding), now, run_id, finding_id),
|
|
659
|
+
)
|
|
660
|
+
updated = self._advance_run(connection, run, now)
|
|
661
|
+
self._record_event(
|
|
662
|
+
connection,
|
|
663
|
+
run_id,
|
|
664
|
+
updated["revision"],
|
|
665
|
+
"patch-proposal-recorded",
|
|
666
|
+
{"artifact_id": artifact_id, "finding_ids": finding_ids, "proposal_count": len(finding_ids)},
|
|
667
|
+
now,
|
|
668
|
+
)
|
|
669
|
+
return {"run": updated, "artifact_id": artifact_id, "proposal_count": len(finding_ids)}
|
|
670
|
+
|
|
671
|
+
def transition(
|
|
672
|
+
self,
|
|
673
|
+
run_id: str,
|
|
674
|
+
expected_revision: int,
|
|
675
|
+
lease_token: str,
|
|
676
|
+
next_state: str,
|
|
677
|
+
next_outcome: str,
|
|
678
|
+
observed_snapshot_hash: str,
|
|
679
|
+
now: int,
|
|
680
|
+
) -> dict[str, Any]:
|
|
681
|
+
with self._transaction() as connection:
|
|
682
|
+
run = self._require_run(connection, run_id)
|
|
683
|
+
self._require_lease(connection, run_id, lease_token, now)
|
|
684
|
+
self._require_revision(run, expected_revision)
|
|
685
|
+
if run["state"] in FINAL_STATES:
|
|
686
|
+
raise InvalidTransition(f"final run state cannot transition: {run['state']}")
|
|
687
|
+
if observed_snapshot_hash != run["current_snapshot_hash"]:
|
|
688
|
+
run["state"] = "SNAPSHOT_STALE"
|
|
689
|
+
run["outcome"] = "SNAPSHOT_STALE"
|
|
690
|
+
run["current_snapshot_hash"] = observed_snapshot_hash
|
|
691
|
+
updated = self._write_run(connection, run, now)
|
|
692
|
+
self._record_event(connection, run_id, updated["revision"], "snapshot-stale", {"observed_snapshot_hash": observed_snapshot_hash}, now)
|
|
693
|
+
return updated
|
|
694
|
+
allowed = ALLOWED_TRANSITIONS.get(run["state"], set())
|
|
695
|
+
if next_state not in allowed and next_state not in {"BLOCKED", "CANCELLED", "STALE"}:
|
|
696
|
+
raise InvalidTransition(f"{run['state']} cannot transition to {next_state}")
|
|
697
|
+
if next_state in TERMINAL_OUTCOMES and next_outcome != next_state:
|
|
698
|
+
raise InvalidTransition("terminal state and outcome must match")
|
|
699
|
+
if next_state not in TERMINAL_OUTCOMES and next_outcome != "IN_PROGRESS":
|
|
700
|
+
raise InvalidTransition("non-terminal states require IN_PROGRESS outcome")
|
|
701
|
+
run["state"] = next_state
|
|
702
|
+
run["outcome"] = next_outcome
|
|
703
|
+
updated = self._write_run(connection, run, now)
|
|
704
|
+
self._record_event(connection, run_id, updated["revision"], "state-transition", {"state": next_state, "outcome": next_outcome}, now)
|
|
705
|
+
return updated
|
|
706
|
+
|
|
707
|
+
def list_events(self, run_id: str) -> list[dict[str, Any]]:
|
|
708
|
+
with self._connection() as connection:
|
|
709
|
+
rows = connection.execute("SELECT * FROM events WHERE run_id = ? ORDER BY sequence", (run_id,)).fetchall()
|
|
710
|
+
return [
|
|
711
|
+
{"sequence": row["sequence"], "revision": row["revision"], "event_type": row["event_type"], "payload": json.loads(row["payload_json"]), "created_at": row["created_at"]}
|
|
712
|
+
for row in rows
|
|
713
|
+
]
|
|
714
|
+
|
|
715
|
+
def list_findings(self, run_id: str) -> list[dict[str, Any]]:
|
|
716
|
+
with self._connection() as connection:
|
|
717
|
+
rows = connection.execute(
|
|
718
|
+
"SELECT finding_json FROM findings WHERE run_id = ? ORDER BY finding_id", (run_id,)
|
|
719
|
+
).fetchall()
|
|
720
|
+
return [json.loads(row["finding_json"]) for row in rows]
|
|
721
|
+
|
|
722
|
+
def list_artifacts(self, run_id: str) -> list[dict[str, Any]]:
|
|
723
|
+
with self._connection() as connection:
|
|
724
|
+
rows = connection.execute(
|
|
725
|
+
"SELECT artifact_id, kind, actor, input_artifact_refs_json, content_hash, body, redaction_status, revision, created_at "
|
|
726
|
+
"FROM artifacts WHERE run_id = ? ORDER BY sequence",
|
|
727
|
+
(run_id,),
|
|
728
|
+
).fetchall()
|
|
729
|
+
return [
|
|
730
|
+
{
|
|
731
|
+
"artifact_id": row["artifact_id"],
|
|
732
|
+
"kind": row["kind"],
|
|
733
|
+
"actor": row["actor"],
|
|
734
|
+
"input_artifact_refs": json.loads(row["input_artifact_refs_json"]),
|
|
735
|
+
"content_hash": row["content_hash"],
|
|
736
|
+
"body": row["body"],
|
|
737
|
+
"redaction_status": row["redaction_status"],
|
|
738
|
+
"revision": row["revision"],
|
|
739
|
+
"created_at": row["created_at"],
|
|
740
|
+
}
|
|
741
|
+
for row in rows
|
|
742
|
+
]
|
|
743
|
+
|
|
744
|
+
def retention_preview(self, now: int) -> dict[str, Any]:
|
|
745
|
+
"""Return an immutable, content-free plan; it never changes the ledger."""
|
|
746
|
+
with self._connection() as connection:
|
|
747
|
+
actions = self._retention_actions(connection, now)
|
|
748
|
+
plan = {"policy_version": "5.0", "generated_at": now, "actions": actions}
|
|
749
|
+
return {**plan, "plan_hash": self._retention_plan_hash(actions)}
|
|
750
|
+
|
|
751
|
+
def empty_retention_preview(self, now: int) -> dict[str, Any]:
|
|
752
|
+
"""Build the read-only result for a state root that has no ledger yet."""
|
|
753
|
+
return {
|
|
754
|
+
"policy_version": "5.0",
|
|
755
|
+
"generated_at": now,
|
|
756
|
+
"actions": [],
|
|
757
|
+
"plan_hash": self._retention_plan_hash([]),
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
def apply_retention(self, plan_hash: str, now: int) -> dict[str, Any]:
|
|
761
|
+
"""Apply only the exact previewed lifecycle plan in one transaction."""
|
|
762
|
+
with self._transaction() as connection:
|
|
763
|
+
actions = self._retention_actions(connection, now)
|
|
764
|
+
actual_hash = self._retention_plan_hash(actions)
|
|
765
|
+
if not secrets.compare_digest(plan_hash, actual_hash):
|
|
766
|
+
raise RetentionPlanStale("retention plan changed; run retention-preview again")
|
|
767
|
+
completed: list[dict[str, Any]] = []
|
|
768
|
+
for action in actions:
|
|
769
|
+
run_id = action["run_id"]
|
|
770
|
+
kind = action["action"]
|
|
771
|
+
if kind == "mark-stale":
|
|
772
|
+
run = self._require_run(connection, run_id)
|
|
773
|
+
run["state"] = "STALE"
|
|
774
|
+
run["outcome"] = "STALE"
|
|
775
|
+
updated = self._write_run(connection, run, now)
|
|
776
|
+
self._record_event(connection, run_id, updated["revision"], "retention-stale", {}, now)
|
|
777
|
+
elif kind == "purge-run":
|
|
778
|
+
connection.execute("DELETE FROM runs WHERE run_id = ?", (run_id,))
|
|
779
|
+
else: # defensive: `_retention_actions` is the sole producer.
|
|
780
|
+
raise StateStoreError(f"unsupported retention action: {kind}")
|
|
781
|
+
completed.append(action)
|
|
782
|
+
return {"plan_hash": plan_hash, "applied_at": now, "actions": completed}
|
|
783
|
+
|
|
784
|
+
def get_finding_by_fingerprint(self, run_id: str, fingerprint: str) -> dict[str, Any] | None:
|
|
785
|
+
with self._connection() as connection:
|
|
786
|
+
row = connection.execute(
|
|
787
|
+
"SELECT finding_json FROM findings WHERE run_id = ? AND fingerprint = ?",
|
|
788
|
+
(run_id, fingerprint),
|
|
789
|
+
).fetchone()
|
|
790
|
+
return None if row is None else json.loads(row["finding_json"])
|
|
791
|
+
|
|
792
|
+
def _retention_actions(self, connection: sqlite3.Connection, now: int) -> list[dict[str, Any]]:
|
|
793
|
+
actions: list[dict[str, Any]] = []
|
|
794
|
+
active_leases = {
|
|
795
|
+
row["run_id"]
|
|
796
|
+
for row in connection.execute("SELECT run_id FROM leases WHERE expires_at > ?", (now,))
|
|
797
|
+
}
|
|
798
|
+
for row in connection.execute("SELECT run_id, state, updated_at FROM runs ORDER BY run_id"):
|
|
799
|
+
run_id = str(row["run_id"])
|
|
800
|
+
age = now - int(row["updated_at"])
|
|
801
|
+
if run_id in active_leases:
|
|
802
|
+
continue
|
|
803
|
+
if row["state"] not in FINAL_STATES and age >= STALE_AFTER_DAYS * DAY_SECONDS:
|
|
804
|
+
actions.append({"action": "mark-stale", "run_id": run_id})
|
|
805
|
+
elif row["state"] in FINAL_STATES and age >= HOT_ARTIFACT_DAYS * DAY_SECONDS:
|
|
806
|
+
actions.append({"action": "purge-run", "run_id": run_id})
|
|
807
|
+
return actions
|
|
808
|
+
|
|
809
|
+
def _retention_plan_hash(self, actions: list[dict[str, Any]]) -> str:
|
|
810
|
+
return self._digest(self._dump({"policy_version": "5.0", "actions": actions}))
|
|
811
|
+
|
|
812
|
+
@contextmanager
|
|
813
|
+
def _connection(self) -> Iterator[sqlite3.Connection]:
|
|
814
|
+
connection = sqlite3.connect(self.database_path, timeout=5, isolation_level=None)
|
|
815
|
+
connection.row_factory = sqlite3.Row
|
|
816
|
+
connection.execute("PRAGMA foreign_keys = ON")
|
|
817
|
+
try:
|
|
818
|
+
yield connection
|
|
819
|
+
finally:
|
|
820
|
+
connection.close()
|
|
821
|
+
|
|
822
|
+
@contextmanager
|
|
823
|
+
def _transaction(self) -> Iterator[sqlite3.Connection]:
|
|
824
|
+
with self._connection() as connection:
|
|
825
|
+
connection.execute("BEGIN IMMEDIATE")
|
|
826
|
+
try:
|
|
827
|
+
yield connection
|
|
828
|
+
except Exception:
|
|
829
|
+
connection.rollback()
|
|
830
|
+
raise
|
|
831
|
+
else:
|
|
832
|
+
connection.commit()
|
|
833
|
+
|
|
834
|
+
@staticmethod
|
|
835
|
+
def _dump(value: Any) -> str:
|
|
836
|
+
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
|
|
837
|
+
|
|
838
|
+
@staticmethod
|
|
839
|
+
def _digest(value: str) -> str:
|
|
840
|
+
return hashlib.sha256(value.encode("utf-8")).hexdigest()
|
|
841
|
+
|
|
842
|
+
def _require_run(self, connection: sqlite3.Connection, run_id: str) -> dict[str, Any]:
|
|
843
|
+
row = connection.execute("SELECT * FROM runs WHERE run_id = ?", (run_id,)).fetchone()
|
|
844
|
+
if row is None:
|
|
845
|
+
raise KeyError(f"run not found: {run_id}")
|
|
846
|
+
return self._run_from_row(row)
|
|
847
|
+
|
|
848
|
+
@staticmethod
|
|
849
|
+
def _run_revision(connection: sqlite3.Connection, run_id: str) -> int:
|
|
850
|
+
row = connection.execute("SELECT revision FROM runs WHERE run_id = ?", (run_id,)).fetchone()
|
|
851
|
+
if row is None:
|
|
852
|
+
raise KeyError(f"run not found: {run_id}")
|
|
853
|
+
return int(row["revision"])
|
|
854
|
+
|
|
855
|
+
def _run_from_row(self, row: sqlite3.Row) -> dict[str, Any]:
|
|
856
|
+
run = json.loads(row["run_json"])
|
|
857
|
+
run.update(
|
|
858
|
+
{
|
|
859
|
+
"state": row["state"],
|
|
860
|
+
"outcome": row["outcome"],
|
|
861
|
+
"revision": row["revision"],
|
|
862
|
+
"target_snapshot_hash": row["target_snapshot_hash"],
|
|
863
|
+
"current_snapshot_hash": row["current_snapshot_hash"],
|
|
864
|
+
"immutable_anchor": json.loads(row["immutable_anchor_json"]),
|
|
865
|
+
}
|
|
866
|
+
)
|
|
867
|
+
return run
|
|
868
|
+
|
|
869
|
+
def _require_lease(self, connection: sqlite3.Connection, run_id: str, lease_token: str, now: int) -> sqlite3.Row:
|
|
870
|
+
row = connection.execute("SELECT * FROM leases WHERE run_id = ?", (run_id,)).fetchone()
|
|
871
|
+
if row is None or row["expires_at"] <= now or not secrets.compare_digest(row["token_digest"], self._digest(lease_token)):
|
|
872
|
+
raise LeaseInvalid(f"run {run_id} has no matching active lease")
|
|
873
|
+
return row
|
|
874
|
+
|
|
875
|
+
@staticmethod
|
|
876
|
+
def _require_revision(run: dict[str, Any], expected_revision: int) -> None:
|
|
877
|
+
if run["revision"] != expected_revision:
|
|
878
|
+
raise RevisionConflict(f"expected revision {expected_revision}, found {run['revision']}")
|
|
879
|
+
|
|
880
|
+
@staticmethod
|
|
881
|
+
def _require_no_likely_secret(body: str, redaction_status: str) -> None:
|
|
882
|
+
if redaction_status != "caller-attested-redacted":
|
|
883
|
+
return
|
|
884
|
+
kind = likely_secret_kind(body)
|
|
885
|
+
if kind is not None:
|
|
886
|
+
raise SensitiveArtifactError(f"caller-attested content rejected by likely-secret guard: {kind}")
|
|
887
|
+
|
|
888
|
+
@staticmethod
|
|
889
|
+
def _validate_finding_identity(run_id: str, finding: dict[str, Any]) -> None:
|
|
890
|
+
required = {
|
|
891
|
+
"schema_version", "finding_id", "run_id", "fingerprint", "origin_severity",
|
|
892
|
+
"effective_gate", "status", "invariant_id", "evidence_refs", "repeat_count",
|
|
893
|
+
"last_probe", "accepted_risk_decision_ref", "subject_kind", "evidence_plane", "category",
|
|
894
|
+
"evidence_confidence", "impact_scope", "claim_status",
|
|
895
|
+
}
|
|
896
|
+
missing = required - set(finding)
|
|
897
|
+
if missing:
|
|
898
|
+
raise ValueError(f"finding is missing required fields: {sorted(missing)}")
|
|
899
|
+
unexpected = set(finding) - required
|
|
900
|
+
if unexpected:
|
|
901
|
+
raise ValueError(f"finding has unexpected fields: {sorted(unexpected)}")
|
|
902
|
+
if finding["run_id"] != run_id:
|
|
903
|
+
raise ValueError("finding run_id must match target run")
|
|
904
|
+
if finding["origin_severity"] not in FINDING_SEVERITIES:
|
|
905
|
+
raise ValueError("finding origin_severity is invalid")
|
|
906
|
+
if finding["schema_version"] != "5.0":
|
|
907
|
+
raise ValueError("finding schema_version is invalid")
|
|
908
|
+
if finding["effective_gate"] not in FINDING_GATES:
|
|
909
|
+
raise ValueError("finding effective_gate is invalid")
|
|
910
|
+
if finding["status"] not in FINDING_STATUSES:
|
|
911
|
+
raise ValueError("finding status is invalid")
|
|
912
|
+
if re.fullmatch(r"F-[0-9]{3,8}", str(finding["finding_id"])) is None:
|
|
913
|
+
raise ValueError("finding_id is invalid")
|
|
914
|
+
if re.fullmatch(r"[a-f0-9]{64}", str(finding["fingerprint"])) is None:
|
|
915
|
+
raise ValueError("finding fingerprint is invalid")
|
|
916
|
+
if not isinstance(finding["evidence_refs"], list) or not finding["evidence_refs"]:
|
|
917
|
+
raise ValueError("finding evidence_refs must be a non-empty list")
|
|
918
|
+
if not isinstance(finding["repeat_count"], int) or isinstance(finding["repeat_count"], bool) or finding["repeat_count"] < 0:
|
|
919
|
+
raise ValueError("finding repeat_count is invalid")
|
|
920
|
+
if not isinstance(finding["invariant_id"], str) or not finding["invariant_id"]:
|
|
921
|
+
raise ValueError("finding invariant_id is invalid")
|
|
922
|
+
if not isinstance(finding["last_probe"], str) or not finding["last_probe"]:
|
|
923
|
+
raise ValueError("finding last_probe is invalid")
|
|
924
|
+
if not isinstance(finding["accepted_risk_decision_ref"], str) or not finding["accepted_risk_decision_ref"]:
|
|
925
|
+
raise ValueError("finding accepted_risk_decision_ref is invalid")
|
|
926
|
+
validate_finding_classification(
|
|
927
|
+
str(finding["subject_kind"]),
|
|
928
|
+
str(finding["evidence_plane"]),
|
|
929
|
+
str(finding["category"]),
|
|
930
|
+
)
|
|
931
|
+
validate_finding_assessment(
|
|
932
|
+
str(finding["origin_severity"]),
|
|
933
|
+
str(finding["effective_gate"]),
|
|
934
|
+
str(finding["evidence_plane"]),
|
|
935
|
+
str(finding["evidence_confidence"]),
|
|
936
|
+
str(finding["impact_scope"]),
|
|
937
|
+
str(finding["claim_status"]),
|
|
938
|
+
)
|
|
939
|
+
|
|
940
|
+
@staticmethod
|
|
941
|
+
def _validate_new_run(run: dict[str, Any]) -> None:
|
|
942
|
+
required = {
|
|
943
|
+
"schema_version", "run_id", "project_key", "target_snapshot_hash",
|
|
944
|
+
"current_snapshot_hash", "authorization_mode", "state", "outcome",
|
|
945
|
+
"revision", "repair_cycle_count", "max_repair_cycles",
|
|
946
|
+
"open_high_risk_assumptions", "retention_policy_version",
|
|
947
|
+
}
|
|
948
|
+
missing = required - set(run)
|
|
949
|
+
if missing:
|
|
950
|
+
raise ValueError(f"run is missing required fields: {sorted(missing)}")
|
|
951
|
+
if run["schema_version"] != "5.0" or run["retention_policy_version"] != "5.0":
|
|
952
|
+
raise ValueError("run schema or retention policy version is invalid")
|
|
953
|
+
if re.fullmatch(r"run_[a-z0-9]{12,64}", str(run["run_id"])) is None:
|
|
954
|
+
raise ValueError("run_id is invalid")
|
|
955
|
+
for field in ("project_key", "target_snapshot_hash", "current_snapshot_hash"):
|
|
956
|
+
if re.fullmatch(r"[a-f0-9]{64}", str(run[field])) is None:
|
|
957
|
+
raise ValueError(f"{field} is invalid")
|
|
958
|
+
if run["authorization_mode"] not in {"review-only", "bounded-repair", "repair-and-add-tests"}:
|
|
959
|
+
raise ValueError("authorization_mode is invalid")
|
|
960
|
+
if run["state"] not in RUN_STATES or run["outcome"] not in RUN_OUTCOMES:
|
|
961
|
+
raise ValueError("run state or outcome is invalid")
|
|
962
|
+
for field in ("revision", "repair_cycle_count", "open_high_risk_assumptions"):
|
|
963
|
+
if not isinstance(run[field], int) or isinstance(run[field], bool) or run[field] < 0:
|
|
964
|
+
raise ValueError(f"{field} is invalid")
|
|
965
|
+
if not isinstance(run["max_repair_cycles"], int) or isinstance(run["max_repair_cycles"], bool) or not 1 <= run["max_repair_cycles"] <= 5:
|
|
966
|
+
raise ValueError("max_repair_cycles is invalid")
|
|
967
|
+
if run["repair_cycle_count"] > run["max_repair_cycles"]:
|
|
968
|
+
raise ValueError("repair_cycle_count exceeds max_repair_cycles")
|
|
969
|
+
if run["state"] != "DRAFT" or run["outcome"] != "IN_PROGRESS" or run["revision"] != 0:
|
|
970
|
+
raise ValueError("a new run must start at DRAFT revision 0 with IN_PROGRESS outcome")
|
|
971
|
+
|
|
972
|
+
@staticmethod
|
|
973
|
+
def _require_artifact_refs(connection: sqlite3.Connection, run_id: str, refs: list[str]) -> None:
|
|
974
|
+
for artifact_id in refs:
|
|
975
|
+
row = connection.execute("SELECT 1 FROM artifacts WHERE run_id = ? AND artifact_id = ?", (run_id, artifact_id)).fetchone()
|
|
976
|
+
if row is None:
|
|
977
|
+
raise ValueError(f"artifact reference does not resolve: {artifact_id}")
|
|
978
|
+
|
|
979
|
+
@staticmethod
|
|
980
|
+
def _require_accepted_risk_decision(connection: sqlite3.Connection, run_id: str, finding: dict[str, Any]) -> None:
|
|
981
|
+
if finding["status"] != "accepted-risk":
|
|
982
|
+
return
|
|
983
|
+
if finding["origin_severity"] not in {"P2", "P3"}:
|
|
984
|
+
raise ValueError("accepted risk must originate as P2 or P3")
|
|
985
|
+
decision_ref = finding["accepted_risk_decision_ref"]
|
|
986
|
+
if decision_ref == "none":
|
|
987
|
+
raise ValueError("accepted risk requires a user decision artifact")
|
|
988
|
+
row = connection.execute(
|
|
989
|
+
"SELECT kind, actor FROM artifacts WHERE run_id = ? AND artifact_id = ?",
|
|
990
|
+
(run_id, decision_ref),
|
|
991
|
+
).fetchone()
|
|
992
|
+
if row is None or row["kind"] != "decision" or row["actor"] != "user":
|
|
993
|
+
raise ValueError("accepted risk requires a user decision artifact")
|
|
994
|
+
|
|
995
|
+
def _advance_run(self, connection: sqlite3.Connection, run: dict[str, Any], now: int) -> dict[str, Any]:
|
|
996
|
+
run["revision"] += 1
|
|
997
|
+
return self._write_run(connection, run, now, increment_revision=False)
|
|
998
|
+
|
|
999
|
+
def _write_run(self, connection: sqlite3.Connection, run: dict[str, Any], now: int, increment_revision: bool = True) -> dict[str, Any]:
|
|
1000
|
+
if increment_revision:
|
|
1001
|
+
run["revision"] += 1
|
|
1002
|
+
connection.execute(
|
|
1003
|
+
"""
|
|
1004
|
+
UPDATE runs SET target_snapshot_hash = ?, current_snapshot_hash = ?, state = ?,
|
|
1005
|
+
outcome = ?, revision = ?, run_json = ?, updated_at = ? WHERE run_id = ?
|
|
1006
|
+
""",
|
|
1007
|
+
(
|
|
1008
|
+
run["target_snapshot_hash"],
|
|
1009
|
+
run["current_snapshot_hash"],
|
|
1010
|
+
run["state"],
|
|
1011
|
+
run["outcome"],
|
|
1012
|
+
run["revision"],
|
|
1013
|
+
self._dump({key: value for key, value in run.items() if key != "immutable_anchor"}),
|
|
1014
|
+
now,
|
|
1015
|
+
run["run_id"],
|
|
1016
|
+
),
|
|
1017
|
+
)
|
|
1018
|
+
return run
|
|
1019
|
+
|
|
1020
|
+
@staticmethod
|
|
1021
|
+
def _record_event(connection: sqlite3.Connection, run_id: str, revision: int, event_type: str, payload: dict[str, Any], now: int) -> None:
|
|
1022
|
+
connection.execute(
|
|
1023
|
+
"INSERT INTO events (run_id, revision, event_type, payload_json, created_at) VALUES (?, ?, ?, ?, ?)",
|
|
1024
|
+
(run_id, revision, event_type, json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False), now),
|
|
1025
|
+
)
|