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.
Files changed (35) hide show
  1. nlp_refinement/__init__.py +1 -0
  2. nlp_refinement/diagnostic_doe_support.py +84 -0
  3. nlp_refinement/doe_receipt_retention.py +81 -0
  4. nlp_refinement/format_contracts.py +157 -0
  5. nlp_refinement/host_client.py +505 -0
  6. nlp_refinement/host_diagnostics.py +430 -0
  7. nlp_refinement/host_execution_request.py +15 -0
  8. nlp_refinement/host_executor.py +104 -0
  9. nlp_refinement/host_refine.py +82 -0
  10. nlp_refinement/m8_doe_fixtures.py +28 -0
  11. nlp_refinement/m8_review_coordinator.py +370 -0
  12. nlp_refinement/patch_proposal_adapter.py +303 -0
  13. nlp_refinement/refine.py +372 -0
  14. nlp_refinement/repair_feasibility.py +327 -0
  15. nlp_refinement/resources/__init__.py +0 -0
  16. nlp_refinement/resources/prompts/patch-proposal-phase.v5.md +51 -0
  17. nlp_refinement/resources/prompts/review-phase.v5.md +57 -0
  18. nlp_refinement/resources/schemas/v5/acceptance-trace.schema.json +17 -0
  19. nlp_refinement/resources/schemas/v5/artifact.schema.json +17 -0
  20. nlp_refinement/resources/schemas/v5/finding.schema.json +27 -0
  21. nlp_refinement/resources/schemas/v5/patch-proposal-result.schema.json +66 -0
  22. nlp_refinement/resources/schemas/v5/phase-envelope.schema.json +18 -0
  23. nlp_refinement/resources/schemas/v5/retention-policy.schema.json +16 -0
  24. nlp_refinement/resources/schemas/v5/review-result.schema.json +37 -0
  25. nlp_refinement/resources/schemas/v5/run.schema.json +22 -0
  26. nlp_refinement/review_adapter.py +203 -0
  27. nlp_refinement/sensitive_data.py +98 -0
  28. nlp_refinement/state_store.py +1025 -0
  29. nlp_refinement_cli-0.9.0.dist-info/METADATA +300 -0
  30. nlp_refinement_cli-0.9.0.dist-info/RECORD +35 -0
  31. nlp_refinement_cli-0.9.0.dist-info/WHEEL +5 -0
  32. nlp_refinement_cli-0.9.0.dist-info/entry_points.txt +4 -0
  33. nlp_refinement_cli-0.9.0.dist-info/licenses/LICENSE +201 -0
  34. nlp_refinement_cli-0.9.0.dist-info/licenses/NOTICE +4 -0
  35. 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)