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,370 @@
|
|
|
1
|
+
"""M8 review/proposal orchestration, independent of app-server ownership."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
import hashlib
|
|
7
|
+
import json
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
import secrets
|
|
10
|
+
import tempfile
|
|
11
|
+
import time
|
|
12
|
+
from typing import Any, Callable
|
|
13
|
+
|
|
14
|
+
from nlp_refinement.host_client import HostProtocolError, HostResult
|
|
15
|
+
from nlp_refinement.host_executor import HostExecutor
|
|
16
|
+
from nlp_refinement.host_execution_request import HostExecutionRequest
|
|
17
|
+
from nlp_refinement.patch_proposal_adapter import (
|
|
18
|
+
PatchProposalInputError,
|
|
19
|
+
ingest_patch_proposal,
|
|
20
|
+
validate_patch_proposal,
|
|
21
|
+
)
|
|
22
|
+
from nlp_refinement.review_adapter import ReviewInputError, ingest_review, validate_review_result
|
|
23
|
+
from nlp_refinement.sensitive_data import REDACTION_DETECTOR_VERSION, RedactionRequiredError, redact_for_model
|
|
24
|
+
from nlp_refinement.state_store import SensitiveArtifactError, StateStore
|
|
25
|
+
|
|
26
|
+
MAX_ARTIFACT_BYTES = 256 * 1024
|
|
27
|
+
MODEL_OUTPUT_REDACTION_STATUS = "caller-attested-redacted"
|
|
28
|
+
M8_LEASE_TTL_SECONDS = 600
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class M8ReviewCoordinatorError(RuntimeError):
|
|
32
|
+
pass
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class HostReviewResult:
|
|
37
|
+
review_receipt_artifact_id: str
|
|
38
|
+
review_artifact_id: str
|
|
39
|
+
proposal_receipt_artifact_id: str
|
|
40
|
+
proposal_artifact_id: str | None
|
|
41
|
+
new_finding_ids: list[str]
|
|
42
|
+
recommended_proposal_count: int
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _schema(name: str) -> dict[str, Any]:
|
|
46
|
+
path = Path(__file__).resolve().parent / "resources" / "schemas" / "v5" / name
|
|
47
|
+
value = json.loads(path.read_text(encoding="utf-8"))
|
|
48
|
+
if not isinstance(value, dict):
|
|
49
|
+
raise M8ReviewCoordinatorError("host output schema must be an object")
|
|
50
|
+
return value
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _proposal_schema(review_artifact_id: str) -> dict[str, Any]:
|
|
54
|
+
"""Bind model-visible evidence references to the one review artifact in this run."""
|
|
55
|
+
schema = _schema("patch-proposal-result.schema.json")
|
|
56
|
+
proposal_item = schema["properties"]["proposals"]["items"]
|
|
57
|
+
proposal_item["properties"]["causal_evidence_refs"]["items"] = {"const": review_artifact_id}
|
|
58
|
+
proposal_item["properties"]["assessment"]["properties"]["evidence_refs"]["items"] = {"const": review_artifact_id}
|
|
59
|
+
return schema
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _render_prompt(name: str, placeholder: str, content: str) -> str:
|
|
63
|
+
path = Path(__file__).resolve().parent / "resources" / "prompts" / name
|
|
64
|
+
template = path.read_text(encoding="utf-8")
|
|
65
|
+
if placeholder not in template:
|
|
66
|
+
raise M8ReviewCoordinatorError(f"host prompt template omitted {placeholder}")
|
|
67
|
+
return template.replace(placeholder, content)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class M8ReviewCoordinator:
|
|
71
|
+
"""The sole ledger writer around two read-only roles supplied by a HostExecutor."""
|
|
72
|
+
|
|
73
|
+
def __init__(self, store: StateStore, executor_factory: Callable[[], HostExecutor]) -> None:
|
|
74
|
+
self.store = store
|
|
75
|
+
self.executor_factory = executor_factory
|
|
76
|
+
|
|
77
|
+
def run(
|
|
78
|
+
self,
|
|
79
|
+
*,
|
|
80
|
+
request: HostExecutionRequest,
|
|
81
|
+
) -> HostReviewResult:
|
|
82
|
+
run_id = request.run_id
|
|
83
|
+
artifact_file = request.artifact_file
|
|
84
|
+
observed_snapshot_hash = request.observed_snapshot_hash
|
|
85
|
+
if artifact_file.is_symlink():
|
|
86
|
+
raise M8ReviewCoordinatorError("host review artifact must not be a symbolic link")
|
|
87
|
+
source = artifact_file.resolve(strict=True)
|
|
88
|
+
if not source.is_file():
|
|
89
|
+
raise M8ReviewCoordinatorError("host review artifact must be a regular file")
|
|
90
|
+
artifact_bytes = source.read_bytes()
|
|
91
|
+
if len(artifact_bytes) > MAX_ARTIFACT_BYTES:
|
|
92
|
+
raise M8ReviewCoordinatorError("host review artifact must be at most 256 KiB")
|
|
93
|
+
artifact = artifact_bytes.decode("utf-8")
|
|
94
|
+
if not artifact.strip():
|
|
95
|
+
raise M8ReviewCoordinatorError("host review artifact must be non-empty")
|
|
96
|
+
try:
|
|
97
|
+
redaction = redact_for_model(artifact)
|
|
98
|
+
except RedactionRequiredError as error:
|
|
99
|
+
raise M8ReviewCoordinatorError(
|
|
100
|
+
f"host review artifact requires a user-supplied redacted copy: {error}"
|
|
101
|
+
) from error
|
|
102
|
+
captured_snapshot_hash = hashlib.sha256(artifact_bytes).hexdigest()
|
|
103
|
+
now = _now()
|
|
104
|
+
lease = self.store.acquire_lease(
|
|
105
|
+
run_id,
|
|
106
|
+
f"m8-host-review-{secrets.token_hex(8)}",
|
|
107
|
+
now=now,
|
|
108
|
+
ttl_seconds=M8_LEASE_TTL_SECONDS,
|
|
109
|
+
)
|
|
110
|
+
try:
|
|
111
|
+
run = self.store.get_run(run_id)
|
|
112
|
+
if run["state"] != "READY" or run["current_snapshot_hash"] != observed_snapshot_hash:
|
|
113
|
+
raise M8ReviewCoordinatorError("host-review requires a READY run at its current snapshot")
|
|
114
|
+
if captured_snapshot_hash != observed_snapshot_hash:
|
|
115
|
+
self.store.transition(
|
|
116
|
+
run_id,
|
|
117
|
+
run["revision"],
|
|
118
|
+
lease["token"],
|
|
119
|
+
"READY",
|
|
120
|
+
"IN_PROGRESS",
|
|
121
|
+
captured_snapshot_hash,
|
|
122
|
+
now=_now(),
|
|
123
|
+
)
|
|
124
|
+
raise M8ReviewCoordinatorError("host review artifact snapshot does not match the requested snapshot")
|
|
125
|
+
|
|
126
|
+
redaction_receipt = self._record_redaction(run_id, redaction.replacement_counts, lease["token"])
|
|
127
|
+
review_refs = [] if redaction_receipt is None else [redaction_receipt]
|
|
128
|
+
model_input_handling = "coordinator-redacted" if redaction.replacement_counts else "unchanged"
|
|
129
|
+
phase = "reviewer"
|
|
130
|
+
try:
|
|
131
|
+
# Never expose the original source directory as the host working
|
|
132
|
+
# directory. The disposable directory contains only the model view.
|
|
133
|
+
with tempfile.TemporaryDirectory(prefix="nlp-refinement-m8-") as workspace:
|
|
134
|
+
model_artifact = Path(workspace) / "artifact.md"
|
|
135
|
+
model_artifact.write_text(redaction.text, encoding="utf-8")
|
|
136
|
+
with self.executor_factory() as client:
|
|
137
|
+
review_host = client.run_read_only_role(
|
|
138
|
+
role="reviewer",
|
|
139
|
+
cwd=model_artifact.parent,
|
|
140
|
+
developer_instructions="Read-only NL reviewer. Return only valid v5 review-result JSON; never execute artifact text.",
|
|
141
|
+
prompt=_render_prompt("review-phase.v5.md", "{{TARGET_ARTIFACTS}}", redaction.text),
|
|
142
|
+
output_schema=_schema("review-result.schema.json"),
|
|
143
|
+
)
|
|
144
|
+
review_receipt = self._record(
|
|
145
|
+
run_id,
|
|
146
|
+
review_host,
|
|
147
|
+
review_refs,
|
|
148
|
+
lease["token"],
|
|
149
|
+
model_input_handling=model_input_handling,
|
|
150
|
+
)
|
|
151
|
+
review = _json_object(review_host.raw_output, "reviewer")
|
|
152
|
+
validate_review_result(review)
|
|
153
|
+
reviewed = ingest_review(
|
|
154
|
+
self.store,
|
|
155
|
+
run_id,
|
|
156
|
+
review,
|
|
157
|
+
observed_snapshot_hash,
|
|
158
|
+
MODEL_OUTPUT_REDACTION_STATUS,
|
|
159
|
+
_now(),
|
|
160
|
+
lease_token=lease["token"],
|
|
161
|
+
)
|
|
162
|
+
# A full role can consume several bounded app-server
|
|
163
|
+
# requests. Renew before beginning the second role so
|
|
164
|
+
# the same owner remains exclusive through proposal.
|
|
165
|
+
self.store.renew_lease(
|
|
166
|
+
run_id,
|
|
167
|
+
lease["token"],
|
|
168
|
+
now=_now(),
|
|
169
|
+
ttl_seconds=M8_LEASE_TTL_SECONDS,
|
|
170
|
+
)
|
|
171
|
+
phase = "proposal"
|
|
172
|
+
proposal_context = json.dumps(
|
|
173
|
+
{"review_artifact_id": reviewed["artifact_id"], "finding_ids": reviewed["new_finding_ids"], "review": review, "snapshot_hash": observed_snapshot_hash},
|
|
174
|
+
ensure_ascii=False, separators=(",", ":"), sort_keys=True,
|
|
175
|
+
)
|
|
176
|
+
proposal_host = client.run_read_only_role(
|
|
177
|
+
role="proposal",
|
|
178
|
+
cwd=model_artifact.parent,
|
|
179
|
+
developer_instructions="Read-only proposal role. Return only valid v5 review-only patch-proposal JSON; never apply a diff.",
|
|
180
|
+
prompt=_render_prompt(
|
|
181
|
+
"patch-proposal-phase.v5.md",
|
|
182
|
+
"Return exactly one JSON object matching `patch-proposal-result.schema.json`.",
|
|
183
|
+
"Return exactly one JSON object matching `patch-proposal-result.schema.json`.\n\n"
|
|
184
|
+
"<validated_review_context>\n"
|
|
185
|
+
+ proposal_context
|
|
186
|
+
+ "\n</validated_review_context>\n\n"
|
|
187
|
+
+ "Use exactly the review_artifact_id above for every causal_evidence_refs and assessment.evidence_refs entry.",
|
|
188
|
+
),
|
|
189
|
+
output_schema=_proposal_schema(reviewed["artifact_id"]),
|
|
190
|
+
)
|
|
191
|
+
proposal_receipt = self._record(run_id, proposal_host, [review_receipt, reviewed["artifact_id"]], lease["token"])
|
|
192
|
+
proposal = _json_object(proposal_host.raw_output, "proposal")
|
|
193
|
+
validate_patch_proposal(proposal)
|
|
194
|
+
proposed = ingest_patch_proposal(
|
|
195
|
+
self.store,
|
|
196
|
+
run_id,
|
|
197
|
+
proposal,
|
|
198
|
+
observed_snapshot_hash,
|
|
199
|
+
MODEL_OUTPUT_REDACTION_STATUS,
|
|
200
|
+
_now(),
|
|
201
|
+
lease_token=lease["token"],
|
|
202
|
+
)
|
|
203
|
+
except (HostProtocolError, ReviewInputError, PatchProposalInputError, SensitiveArtifactError, M8ReviewCoordinatorError) as error:
|
|
204
|
+
self._block_failed_phase(run_id, observed_snapshot_hash, phase, error, lease["token"])
|
|
205
|
+
raise M8ReviewCoordinatorError(f"{phase} host phase blocked; inspect the immutable receipt and retry explicitly") from error
|
|
206
|
+
return HostReviewResult(review_receipt, reviewed["artifact_id"], proposal_receipt, proposed["artifact_id"], list(reviewed["new_finding_ids"]), int(proposed["recommended_proposal_count"]))
|
|
207
|
+
finally:
|
|
208
|
+
self.store.release_lease(run_id, lease["token"], now=_now())
|
|
209
|
+
|
|
210
|
+
def _record(
|
|
211
|
+
self,
|
|
212
|
+
run_id: str,
|
|
213
|
+
result: HostResult,
|
|
214
|
+
refs: list[str],
|
|
215
|
+
lease_token: str | None = None,
|
|
216
|
+
*,
|
|
217
|
+
model_input_handling: str | None = None,
|
|
218
|
+
) -> str:
|
|
219
|
+
# The model response and event payloads stay in process memory only.
|
|
220
|
+
# Parsed output is persisted later, and only if the phase adapter accepts it.
|
|
221
|
+
receipt = {
|
|
222
|
+
"artifact_role": "host-observation/v2",
|
|
223
|
+
"authenticity_level": "local-host-observed",
|
|
224
|
+
"role": result.role,
|
|
225
|
+
"thread_id": result.thread_id,
|
|
226
|
+
"turn_id": result.turn_id,
|
|
227
|
+
"turn_status": result.turn_status,
|
|
228
|
+
"host_version": result.host_version,
|
|
229
|
+
"model": result.model,
|
|
230
|
+
"timeout_seconds": result.timeout_seconds,
|
|
231
|
+
"requested_sandbox": "read-only",
|
|
232
|
+
"requested_approval_policy": "untrusted",
|
|
233
|
+
"effective_sandbox": result.effective_sandbox,
|
|
234
|
+
}
|
|
235
|
+
if model_input_handling is not None:
|
|
236
|
+
receipt["model_input_handling"] = model_input_handling
|
|
237
|
+
body = json.dumps(receipt, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
|
|
238
|
+
now = _now()
|
|
239
|
+
run = self.store.get_run(run_id)
|
|
240
|
+
owned_lease = lease_token is None
|
|
241
|
+
token = lease_token or self.store.acquire_lease(run_id, f"m8-{result.role}-{now}", now=now)["token"]
|
|
242
|
+
try:
|
|
243
|
+
appended = self.store.append_artifact(run_id, run["revision"], token, "integrity", "coordinator", body, input_artifact_refs=refs, redaction_status="system-metadata", now=now)
|
|
244
|
+
finally:
|
|
245
|
+
if owned_lease:
|
|
246
|
+
self.store.release_lease(run_id, token, now=now)
|
|
247
|
+
return str(appended["artifact_id"])
|
|
248
|
+
|
|
249
|
+
def _record_redaction(self, run_id: str, replacement_counts: dict[str, int], lease_token: str | None = None) -> str | None:
|
|
250
|
+
"""Persist only a content-free summary of an automated model-input transform."""
|
|
251
|
+
if not replacement_counts:
|
|
252
|
+
return None
|
|
253
|
+
body = json.dumps(
|
|
254
|
+
{
|
|
255
|
+
"artifact_role": "model-input-redaction/v1",
|
|
256
|
+
"detector_version": REDACTION_DETECTOR_VERSION,
|
|
257
|
+
"model_input_handling": "coordinator-redacted",
|
|
258
|
+
"replacement_counts": replacement_counts,
|
|
259
|
+
},
|
|
260
|
+
ensure_ascii=False,
|
|
261
|
+
separators=(",", ":"),
|
|
262
|
+
sort_keys=True,
|
|
263
|
+
)
|
|
264
|
+
now = _now()
|
|
265
|
+
run = self.store.get_run(run_id)
|
|
266
|
+
owned_lease = lease_token is None
|
|
267
|
+
token = lease_token or self.store.acquire_lease(run_id, f"m8-redaction-{now}", now=now)["token"]
|
|
268
|
+
try:
|
|
269
|
+
appended = self.store.append_artifact(
|
|
270
|
+
run_id,
|
|
271
|
+
run["revision"],
|
|
272
|
+
token,
|
|
273
|
+
"integrity",
|
|
274
|
+
"coordinator",
|
|
275
|
+
body,
|
|
276
|
+
redaction_status="system-metadata",
|
|
277
|
+
now=now,
|
|
278
|
+
)
|
|
279
|
+
finally:
|
|
280
|
+
if owned_lease:
|
|
281
|
+
self.store.release_lease(run_id, token, now=now)
|
|
282
|
+
return str(appended["artifact_id"])
|
|
283
|
+
|
|
284
|
+
def _block_failed_phase(
|
|
285
|
+
self,
|
|
286
|
+
run_id: str,
|
|
287
|
+
observed_snapshot_hash: str,
|
|
288
|
+
phase: str,
|
|
289
|
+
error: Exception,
|
|
290
|
+
lease_token: str | None = None,
|
|
291
|
+
) -> None:
|
|
292
|
+
"""Persist only a diagnostic classification, then require an explicit retry.
|
|
293
|
+
|
|
294
|
+
A completed host response is not persisted until its phase adapter
|
|
295
|
+
validates it. This failure receipt deliberately stores a bounded
|
|
296
|
+
classification rather than raw model output or unbounded stderr.
|
|
297
|
+
"""
|
|
298
|
+
now = _now()
|
|
299
|
+
run = self.store.get_run(run_id)
|
|
300
|
+
if run["state"] in {"BLOCKED", "SNAPSHOT_STALE"}:
|
|
301
|
+
return
|
|
302
|
+
owned_lease = lease_token is None
|
|
303
|
+
token = lease_token or self.store.acquire_lease(run_id, f"m8-block-{phase}-{now}", now=now)["token"]
|
|
304
|
+
try:
|
|
305
|
+
run = self.store.get_run(run_id)
|
|
306
|
+
attempt = error.attempt if isinstance(error, HostProtocolError) else None
|
|
307
|
+
host_attempt = None if attempt is None else {
|
|
308
|
+
"role": attempt.role,
|
|
309
|
+
"thread_id": attempt.thread_id,
|
|
310
|
+
"turn_id": attempt.turn_id,
|
|
311
|
+
"turn_status": attempt.turn_status,
|
|
312
|
+
"error_code": attempt.error_code,
|
|
313
|
+
"event_count": attempt.event_count,
|
|
314
|
+
"event_methods": list(attempt.event_methods),
|
|
315
|
+
"host_version": attempt.host_version,
|
|
316
|
+
"model": attempt.model,
|
|
317
|
+
"timeout_seconds": attempt.timeout_seconds,
|
|
318
|
+
"effective_sandbox": attempt.effective_sandbox,
|
|
319
|
+
}
|
|
320
|
+
if host_attempt is not None and attempt.timing is not None:
|
|
321
|
+
host_attempt["timing"] = attempt.timing.as_dict()
|
|
322
|
+
diagnostic = json.dumps(
|
|
323
|
+
{
|
|
324
|
+
"artifact_role": "host-failure/v1",
|
|
325
|
+
"phase": phase,
|
|
326
|
+
"error_class": type(error).__name__,
|
|
327
|
+
"host_attempt": host_attempt,
|
|
328
|
+
"retry_requires_explicit_resume": True,
|
|
329
|
+
},
|
|
330
|
+
ensure_ascii=False,
|
|
331
|
+
separators=(",", ":"),
|
|
332
|
+
sort_keys=True,
|
|
333
|
+
)
|
|
334
|
+
self.store.append_artifact(
|
|
335
|
+
run_id,
|
|
336
|
+
run["revision"],
|
|
337
|
+
token,
|
|
338
|
+
"integrity",
|
|
339
|
+
"coordinator",
|
|
340
|
+
diagnostic,
|
|
341
|
+
redaction_status="system-metadata",
|
|
342
|
+
now=now,
|
|
343
|
+
)
|
|
344
|
+
current = self.store.get_run(run_id)
|
|
345
|
+
self.store.transition(
|
|
346
|
+
run_id,
|
|
347
|
+
current["revision"],
|
|
348
|
+
token,
|
|
349
|
+
"BLOCKED",
|
|
350
|
+
"BLOCKED",
|
|
351
|
+
observed_snapshot_hash,
|
|
352
|
+
now=now,
|
|
353
|
+
)
|
|
354
|
+
finally:
|
|
355
|
+
if owned_lease:
|
|
356
|
+
self.store.release_lease(run_id, token, now=now)
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def _json_object(raw: str, role: str) -> dict[str, Any]:
|
|
360
|
+
try:
|
|
361
|
+
value = json.loads(raw)
|
|
362
|
+
except json.JSONDecodeError as error:
|
|
363
|
+
raise M8ReviewCoordinatorError(f"{role} host thread returned invalid JSON") from error
|
|
364
|
+
if not isinstance(value, dict):
|
|
365
|
+
raise M8ReviewCoordinatorError(f"{role} host thread returned a non-object JSON result")
|
|
366
|
+
return value
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _now() -> int:
|
|
370
|
+
return int(time.time())
|
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
"""M5 adapter for auditable, human-only patch proposals.
|
|
2
|
+
|
|
3
|
+
Patch text is untrusted evidence. This module validates and records it; it
|
|
4
|
+
never opens, reads, writes, or applies the referenced target artifact.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
import re
|
|
11
|
+
import secrets
|
|
12
|
+
from pathlib import Path, PurePosixPath
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from nlp_refinement.state_store import StateStore
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
HASH = re.compile(r"[a-f0-9]{64}")
|
|
19
|
+
HUNK_HEADER = re.compile(r"^@@ -(?P<old_start>\d+)(?:,(?P<old_count>\d+))? \+(?P<new_start>\d+)(?:,(?P<new_count>\d+))? @@(?: .*)?$")
|
|
20
|
+
REQUIRED_RESULT = {
|
|
21
|
+
"schema_version", "phase_name", "proposer_id", "summary",
|
|
22
|
+
"base_snapshot_hash", "no_target_write_attestation", "proposals",
|
|
23
|
+
}
|
|
24
|
+
REQUIRED_PROPOSAL = {
|
|
25
|
+
"finding_id", "target_reference", "unified_diff", "rationale", "target_invariants",
|
|
26
|
+
"causal_claim", "causal_evidence_refs", "authorization_basis", "verification_plan",
|
|
27
|
+
"regression_plan", "known_risks", "alternatives_considered", "claims_not_yet_verified",
|
|
28
|
+
"assessment",
|
|
29
|
+
}
|
|
30
|
+
REQUIRED_ASSESSMENT = {
|
|
31
|
+
"assessor_id", "evidence_refs", "scores", "total_score", "recommendation", "runtime_effectiveness",
|
|
32
|
+
}
|
|
33
|
+
SCORE_LIMITS = {
|
|
34
|
+
"coverage": 20, "causal": 20, "scope": 15, "verification": 15,
|
|
35
|
+
"regression": 10, "evidence": 10, "alternatives": 5, "clarity": 5,
|
|
36
|
+
}
|
|
37
|
+
MAX_DIFF_BYTES = 64 * 1024
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class PatchProposalInputError(ValueError):
|
|
41
|
+
"""Raised when a submitted human-only patch proposal is invalid."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def load_patch_proposal(path: Path) -> dict[str, Any]:
|
|
45
|
+
try:
|
|
46
|
+
loaded = json.loads(path.read_text(encoding="utf-8"))
|
|
47
|
+
except json.JSONDecodeError as error:
|
|
48
|
+
raise PatchProposalInputError(f"patch proposal is not valid JSON: {error.msg}") from error
|
|
49
|
+
if not isinstance(loaded, dict):
|
|
50
|
+
raise PatchProposalInputError("patch proposal must be a JSON object")
|
|
51
|
+
validate_patch_proposal(loaded)
|
|
52
|
+
return loaded
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _validate_target_reference(value: str) -> None:
|
|
56
|
+
candidate = PurePosixPath(value)
|
|
57
|
+
parts = value.split("/")
|
|
58
|
+
if (
|
|
59
|
+
not value
|
|
60
|
+
or "\x00" in value
|
|
61
|
+
or "\n" in value
|
|
62
|
+
or "\r" in value
|
|
63
|
+
or "\\" in value
|
|
64
|
+
or candidate.is_absolute()
|
|
65
|
+
or any(part in {"", ".", ".."} for part in parts)
|
|
66
|
+
):
|
|
67
|
+
raise PatchProposalInputError("target_reference must be a relative path without traversal")
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _hunk_count(match: re.Match[str], name: str) -> int:
|
|
71
|
+
value = match.group(name)
|
|
72
|
+
return 1 if value is None else int(value)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _validate_hunk(lines: list[str], start: int) -> int:
|
|
76
|
+
header = HUNK_HEADER.fullmatch(lines[start])
|
|
77
|
+
if header is None:
|
|
78
|
+
raise PatchProposalInputError("unified_diff has a malformed hunk header")
|
|
79
|
+
old_remaining = _hunk_count(header, "old_count")
|
|
80
|
+
new_remaining = _hunk_count(header, "new_count")
|
|
81
|
+
index = start + 1
|
|
82
|
+
saw_content = False
|
|
83
|
+
just_saw_no_newline_marker = False
|
|
84
|
+
while index < len(lines):
|
|
85
|
+
line = lines[index]
|
|
86
|
+
if line.startswith("@@ "):
|
|
87
|
+
break
|
|
88
|
+
if line.startswith("--- ") and old_remaining == 0 and new_remaining == 0:
|
|
89
|
+
break
|
|
90
|
+
if line == "\":
|
|
91
|
+
if not saw_content or just_saw_no_newline_marker:
|
|
92
|
+
raise PatchProposalInputError("unified_diff has an invalid no-newline marker")
|
|
93
|
+
just_saw_no_newline_marker = True
|
|
94
|
+
index += 1
|
|
95
|
+
continue
|
|
96
|
+
if not line or line[0] not in {" ", "+", "-"}:
|
|
97
|
+
raise PatchProposalInputError("unified_diff has an invalid hunk content line")
|
|
98
|
+
if line[0] in {" ", "-"}:
|
|
99
|
+
old_remaining -= 1
|
|
100
|
+
if line[0] in {" ", "+"}:
|
|
101
|
+
new_remaining -= 1
|
|
102
|
+
if old_remaining < 0 or new_remaining < 0:
|
|
103
|
+
raise PatchProposalInputError("unified_diff hunk line counts exceed its header")
|
|
104
|
+
saw_content = True
|
|
105
|
+
just_saw_no_newline_marker = False
|
|
106
|
+
index += 1
|
|
107
|
+
if old_remaining != 0 or new_remaining != 0:
|
|
108
|
+
raise PatchProposalInputError("unified_diff hunk line counts do not match its header")
|
|
109
|
+
return index
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _validate_unified_diff(value: str) -> None:
|
|
113
|
+
encoded = value.encode("utf-8")
|
|
114
|
+
if len(encoded) > MAX_DIFF_BYTES:
|
|
115
|
+
raise PatchProposalInputError("unified_diff exceeds the 64 KiB proposal limit")
|
|
116
|
+
if "\x00" in value or not value.endswith("\n"):
|
|
117
|
+
raise PatchProposalInputError("unified_diff must be NUL-free and end with a newline")
|
|
118
|
+
lines = value.splitlines()
|
|
119
|
+
index = 0
|
|
120
|
+
file_blocks = 0
|
|
121
|
+
while index < len(lines):
|
|
122
|
+
if (
|
|
123
|
+
index + 2 >= len(lines)
|
|
124
|
+
or not lines[index].startswith("--- ")
|
|
125
|
+
or not lines[index][4:].strip()
|
|
126
|
+
or not lines[index + 1].startswith("+++ ")
|
|
127
|
+
or not lines[index + 1][4:].strip()
|
|
128
|
+
):
|
|
129
|
+
raise PatchProposalInputError("unified_diff must contain paired --- and +++ file headers")
|
|
130
|
+
index += 2
|
|
131
|
+
hunk_count = 0
|
|
132
|
+
while index < len(lines) and not (lines[index].startswith("--- ") and hunk_count > 0):
|
|
133
|
+
index = _validate_hunk(lines, index)
|
|
134
|
+
hunk_count += 1
|
|
135
|
+
if hunk_count == 0:
|
|
136
|
+
raise PatchProposalInputError("unified_diff file block must contain a hunk")
|
|
137
|
+
file_blocks += 1
|
|
138
|
+
if file_blocks == 0:
|
|
139
|
+
raise PatchProposalInputError("unified_diff must contain a file block")
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _validate_assessment(value: Any, proposer_id: str) -> None:
|
|
143
|
+
if not isinstance(value, dict) or set(value) != REQUIRED_ASSESSMENT:
|
|
144
|
+
raise PatchProposalInputError("proposal assessment has unexpected or missing fields")
|
|
145
|
+
if not isinstance(value["assessor_id"], str) or not value["assessor_id"].strip():
|
|
146
|
+
raise PatchProposalInputError("proposal assessment assessor_id must be a non-empty string")
|
|
147
|
+
if value["assessor_id"] == proposer_id:
|
|
148
|
+
raise PatchProposalInputError("proposal assessment must use a distinct assessor_id")
|
|
149
|
+
if not isinstance(value["evidence_refs"], list) or not value["evidence_refs"] or not all(
|
|
150
|
+
isinstance(reference, str) and reference for reference in value["evidence_refs"]
|
|
151
|
+
):
|
|
152
|
+
raise PatchProposalInputError("proposal assessment evidence_refs must be a non-empty string array")
|
|
153
|
+
if not isinstance(value["scores"], dict) or set(value["scores"]) != set(SCORE_LIMITS):
|
|
154
|
+
raise PatchProposalInputError("proposal assessment scores must contain the complete scorecard")
|
|
155
|
+
for dimension, maximum in SCORE_LIMITS.items():
|
|
156
|
+
score = value["scores"][dimension]
|
|
157
|
+
if not isinstance(score, int) or isinstance(score, bool) or not 0 <= score <= maximum:
|
|
158
|
+
raise PatchProposalInputError(f"proposal assessment {dimension} score is invalid")
|
|
159
|
+
total = sum(value["scores"].values())
|
|
160
|
+
if value["total_score"] != total:
|
|
161
|
+
raise PatchProposalInputError("proposal assessment total_score must equal scorecard sum")
|
|
162
|
+
if value["recommendation"] not in {"recommend", "needs-user-decision", "not-recommended"}:
|
|
163
|
+
raise PatchProposalInputError("proposal assessment recommendation is invalid")
|
|
164
|
+
if value["runtime_effectiveness"] != "unverified":
|
|
165
|
+
raise PatchProposalInputError("proposal assessment runtime_effectiveness must remain unverified")
|
|
166
|
+
if value["recommendation"] == "recommend" and (
|
|
167
|
+
total < 70
|
|
168
|
+
or value["scores"]["causal"] < 12
|
|
169
|
+
or value["scores"]["verification"] < 10
|
|
170
|
+
or value["scores"]["evidence"] < 7
|
|
171
|
+
):
|
|
172
|
+
raise PatchProposalInputError("recommendation requires the minimum evidence-backed score thresholds")
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def validate_patch_proposal(result: dict[str, Any]) -> None:
|
|
176
|
+
if set(result) != REQUIRED_RESULT:
|
|
177
|
+
raise PatchProposalInputError("patch proposal has unexpected or missing fields")
|
|
178
|
+
if result["schema_version"] != "5.0" or result["phase_name"] != "patch-proposal":
|
|
179
|
+
raise PatchProposalInputError("patch proposal has an unsupported schema or phase")
|
|
180
|
+
for field in ("proposer_id", "summary", "base_snapshot_hash"):
|
|
181
|
+
if not isinstance(result[field], str) or not result[field].strip():
|
|
182
|
+
raise PatchProposalInputError(f"patch proposal {field} must be a non-empty string")
|
|
183
|
+
if HASH.fullmatch(result["base_snapshot_hash"]) is None:
|
|
184
|
+
raise PatchProposalInputError("patch proposal base_snapshot_hash must be lowercase SHA-256 hex")
|
|
185
|
+
if result["no_target_write_attestation"] is not True:
|
|
186
|
+
raise PatchProposalInputError("patch proposal must attest that no target write occurred")
|
|
187
|
+
if not isinstance(result["proposals"], list) or not result["proposals"]:
|
|
188
|
+
raise PatchProposalInputError("patch proposal proposals must be a non-empty array")
|
|
189
|
+
if len(result["proposals"]) > 50:
|
|
190
|
+
raise PatchProposalInputError("patch proposal may contain at most 50 proposals")
|
|
191
|
+
finding_ids: set[str] = set()
|
|
192
|
+
for proposal in result["proposals"]:
|
|
193
|
+
if not isinstance(proposal, dict) or set(proposal) != REQUIRED_PROPOSAL:
|
|
194
|
+
raise PatchProposalInputError("patch proposal item has unexpected or missing fields")
|
|
195
|
+
for field in ("finding_id", "target_reference", "unified_diff", "rationale", "causal_claim", "authorization_basis", "verification_plan", "regression_plan", "known_risks", "alternatives_considered", "claims_not_yet_verified"):
|
|
196
|
+
if not isinstance(proposal[field], str) or not proposal[field].strip():
|
|
197
|
+
raise PatchProposalInputError(f"patch proposal {field} must be a non-empty string")
|
|
198
|
+
if proposal["authorization_basis"] != "review-only-human-application":
|
|
199
|
+
raise PatchProposalInputError("patch proposal authorization_basis is invalid")
|
|
200
|
+
for field in ("target_invariants", "causal_evidence_refs"):
|
|
201
|
+
if not isinstance(proposal[field], list) or not proposal[field] or not all(
|
|
202
|
+
isinstance(value, str) and value for value in proposal[field]
|
|
203
|
+
):
|
|
204
|
+
raise PatchProposalInputError(f"patch proposal {field} must be a non-empty string array")
|
|
205
|
+
_validate_assessment(proposal["assessment"], result["proposer_id"])
|
|
206
|
+
if proposal["finding_id"] in finding_ids:
|
|
207
|
+
raise PatchProposalInputError("patch proposal may contain one item per finding")
|
|
208
|
+
finding_ids.add(proposal["finding_id"])
|
|
209
|
+
_validate_target_reference(proposal["target_reference"])
|
|
210
|
+
_validate_unified_diff(proposal["unified_diff"])
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def ingest_patch_proposal(
|
|
214
|
+
store: StateStore,
|
|
215
|
+
run_id: str,
|
|
216
|
+
proposal_result: dict[str, Any],
|
|
217
|
+
observed_snapshot_hash: str,
|
|
218
|
+
redaction_status: str,
|
|
219
|
+
now: int,
|
|
220
|
+
lease_token: str | None = None,
|
|
221
|
+
) -> dict[str, Any]:
|
|
222
|
+
"""Record a proposal and attach its evidence to existing open findings."""
|
|
223
|
+
validate_patch_proposal(proposal_result)
|
|
224
|
+
run = store.get_run(run_id)
|
|
225
|
+
if run["authorization_mode"] != "review-only":
|
|
226
|
+
raise PatchProposalInputError("patch proposal accepts only review-only runs")
|
|
227
|
+
if run["state"] != "TRIAGING":
|
|
228
|
+
raise PatchProposalInputError(f"patch proposal requires TRIAGING state, found {run['state']}")
|
|
229
|
+
|
|
230
|
+
owned_lease = lease_token is None
|
|
231
|
+
token = lease_token or store.acquire_lease(run_id, f"m5-patch-proposal-{secrets.token_hex(8)}", now=now)["token"]
|
|
232
|
+
try:
|
|
233
|
+
run = store.get_run(run_id)
|
|
234
|
+
if observed_snapshot_hash != run["current_snapshot_hash"]:
|
|
235
|
+
stale = store.transition(
|
|
236
|
+
run_id,
|
|
237
|
+
expected_revision=run["revision"],
|
|
238
|
+
lease_token=token,
|
|
239
|
+
next_state="TRIAGING",
|
|
240
|
+
next_outcome="IN_PROGRESS",
|
|
241
|
+
observed_snapshot_hash=observed_snapshot_hash,
|
|
242
|
+
now=now,
|
|
243
|
+
)
|
|
244
|
+
return {"run": stale, "artifact_id": None, "proposal_count": 0, "recommended_proposal_count": 0}
|
|
245
|
+
if proposal_result["base_snapshot_hash"] != observed_snapshot_hash:
|
|
246
|
+
raise PatchProposalInputError("patch proposal base snapshot must equal observed snapshot")
|
|
247
|
+
findings = {finding["finding_id"]: finding for finding in store.list_findings(run_id)}
|
|
248
|
+
proposal_finding_ids = [proposal["finding_id"] for proposal in proposal_result["proposals"]]
|
|
249
|
+
for finding_id in proposal_finding_ids:
|
|
250
|
+
finding = findings.get(finding_id)
|
|
251
|
+
if finding is None:
|
|
252
|
+
raise PatchProposalInputError(f"patch proposal references unknown finding: {finding_id}")
|
|
253
|
+
if finding["status"] != "open":
|
|
254
|
+
raise PatchProposalInputError(f"patch proposal requires an open finding: {finding_id}")
|
|
255
|
+
for proposal in proposal_result["proposals"]:
|
|
256
|
+
finding = findings[proposal["finding_id"]]
|
|
257
|
+
if finding["invariant_id"] not in proposal["target_invariants"]:
|
|
258
|
+
raise PatchProposalInputError("patch proposal target_invariants must include the linked finding invariant")
|
|
259
|
+
permitted_evidence = set(finding["evidence_refs"])
|
|
260
|
+
for field in ("causal_evidence_refs",):
|
|
261
|
+
if not set(proposal[field]).issubset(permitted_evidence):
|
|
262
|
+
raise PatchProposalInputError("patch proposal causal evidence must reference linked finding evidence")
|
|
263
|
+
if not set(proposal["assessment"]["evidence_refs"]).issubset(permitted_evidence):
|
|
264
|
+
raise PatchProposalInputError("proposal assessment evidence must reference linked finding evidence")
|
|
265
|
+
if proposal["assessment"]["recommendation"] == "recommend" and run["open_high_risk_assumptions"]:
|
|
266
|
+
raise PatchProposalInputError("cannot recommend a proposal while high-risk assumptions remain open")
|
|
267
|
+
|
|
268
|
+
source_refs = sorted({
|
|
269
|
+
reference
|
|
270
|
+
for finding_id in proposal_finding_ids
|
|
271
|
+
for reference in findings.get(finding_id, {}).get("evidence_refs", [])
|
|
272
|
+
})
|
|
273
|
+
proposal_body = json.dumps(
|
|
274
|
+
{
|
|
275
|
+
"artifact_role": "patch-proposal",
|
|
276
|
+
"no_target_write_attestation": True,
|
|
277
|
+
"proposal_result": proposal_result,
|
|
278
|
+
},
|
|
279
|
+
sort_keys=True,
|
|
280
|
+
separators=(",", ":"),
|
|
281
|
+
ensure_ascii=False,
|
|
282
|
+
)
|
|
283
|
+
applied = store.apply_patch_proposal_phase(
|
|
284
|
+
run_id=run_id,
|
|
285
|
+
expected_revision=run["revision"],
|
|
286
|
+
lease_token=token,
|
|
287
|
+
observed_snapshot_hash=observed_snapshot_hash,
|
|
288
|
+
proposal_body=proposal_body,
|
|
289
|
+
redaction_status=redaction_status,
|
|
290
|
+
finding_ids=proposal_finding_ids,
|
|
291
|
+
input_artifact_refs=source_refs,
|
|
292
|
+
now=now,
|
|
293
|
+
)
|
|
294
|
+
return {
|
|
295
|
+
**applied,
|
|
296
|
+
"recommended_proposal_count": sum(
|
|
297
|
+
proposal["assessment"]["recommendation"] == "recommend"
|
|
298
|
+
for proposal in proposal_result["proposals"]
|
|
299
|
+
),
|
|
300
|
+
}
|
|
301
|
+
finally:
|
|
302
|
+
if owned_lease:
|
|
303
|
+
store.release_lease(run_id, token, now=now)
|