okstra 0.237.0 → 0.238.0

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.237.0",
3
+ "version": "0.238.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.237.0",
3
- "builtAt": "2026-11-19T13:45:11.249Z",
2
+ "package": "0.238.0",
3
+ "builtAt": "2026-11-19T15:02:21.983Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -2,6 +2,7 @@
2
2
  from __future__ import annotations
3
3
 
4
4
  from pathlib import Path
5
+ from typing import Literal
5
6
 
6
7
  from .invocation import (
7
8
  AgentInstruction, AgentInstructionSource, AgentInvocationError,
@@ -15,7 +16,7 @@ from ..worker_artifact_paths import audit_sidecar_rel
15
16
 
16
17
  def prepare_evidence_recovery(
17
18
  metadata_path: Path, *, project_root: Path, result_path: Path,
18
- source_attempt: int,
19
+ source_attempt: int, reason: RecoveryReason,
19
20
  ) -> tuple[PreparedAgentInvocation, Path]:
20
21
  """원래 모델·역할을 유지하고 새 결과 경로에 제한된 증거 보완을 발행한다."""
21
22
  metadata = load_owned_object(metadata_path, artifact="recovery source metadata")
@@ -44,7 +45,7 @@ def prepare_evidence_recovery(
44
45
  }
45
46
  anchors = tuple(next((f"{key} {value}" for key, value in replacements.items()
46
47
  if line.startswith(key)), line) for line in _extract_anchor_lines(prefix))
47
- body = _recovery_instructions(identity.invocation_ref, source_attempt, result_path, old_prompt)
48
+ body = _recovery_instructions(identity.invocation_ref, source_attempt, result_path, old_prompt, reason)
48
49
  prepared = prepare_agent_invocation(AgentInvocationRequest(
49
50
  invocation_id=invocation_id, worker_id=None, audience=metadata["audience"],
50
51
  assignment_ref=metadata["assignmentRef"], purpose=None,
@@ -61,14 +62,25 @@ def prepare_evidence_recovery(
61
62
  return prepared, result
62
63
 
63
64
 
64
- def _recovery_instructions(invocation_ref: str, source_attempt: int, result_path: Path, old_prompt: Path) -> str:
65
- """완료된 구현을 재실행하지 않는 보완 범위를 전달한다."""
65
+ RecoveryReason = Literal["declaration", "unsealed"]
66
+
67
+ _RECOVERY_CAUSES: dict[str, str] = {
68
+ "declaration": "The prior attempt failed only on a declaration discrepancy.",
69
+ "unsealed": ("The prior attempt completed, but it closed before okstra sealed attempt evidence, so "
70
+ "its result cannot be read as verification evidence."),
71
+ }
72
+
73
+
74
+ def _recovery_instructions(
75
+ invocation_ref: str, source_attempt: int, result_path: Path, old_prompt: Path, reason: RecoveryReason,
76
+ ) -> str:
77
+ """The recovery scope: keep the completed implementation and rebuild only its evidence."""
66
78
  return (
67
79
  "## Evidence recovery scope\n\n"
68
80
  f"Original invocation: {invocation_ref}; attempt: {source_attempt}.\n"
69
81
  f"Read and preserve the original result: {result_path}.\n"
70
82
  f"Read the original audit: {old_prompt}.mutation-audit.json.\n"
71
- "The prior attempt failed only on a declaration discrepancy. Preserve existing source and QA work. "
83
+ f"{_RECOVERY_CAUSES[reason]} Preserve existing source and QA work. "
72
84
  "Do not repeat completed implementation steps or edit production source. Reconcile the declaration "
73
85
  "and required evidence against current artifacts; retain historical validation as historical. "
74
86
  "Do not invent a missing before-state or claim independent verification. If a substantive defect "
@@ -3,6 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import hashlib
5
5
  import json
6
+ import sys
6
7
  from dataclasses import dataclass, replace
7
8
  from datetime import datetime, timezone
8
9
  from pathlib import Path
@@ -13,6 +14,7 @@ from .execution_identity import (
13
14
  Attempt,
14
15
  ExecutionManifestError,
15
16
  MutationRecoveryDecision,
17
+ build_dispatch_id,
16
18
  )
17
19
  from .execution_manifest import read_execution_manifest
18
20
  from .execution_manifest import _replace_manifest, _write_manifest_over_existing
@@ -41,8 +43,6 @@ class TerminalObservation:
41
43
  changed_paths: tuple[str, ...]
42
44
  artifact_paths: tuple[Path, ...]
43
45
  host_event_stream_path: Path
44
- project_root: Path
45
- worktree: Path | None
46
46
  interrupted_before_record: bool = False
47
47
 
48
48
 
@@ -284,6 +284,83 @@ def finalize_attempt(
284
284
  return seal
285
285
 
286
286
 
287
+ def host_event_stream_path(prompt_path: Path, attempt: int) -> Path:
288
+ """One stream per attempt: a seal pins the stream's bytes, so a retry must not append to it."""
289
+ return prompt_path.with_name(f"{prompt_path.name}.attempt-{attempt}.host-events.jsonl")
290
+
291
+
292
+ def closed_before_sealing(prompt_path: Path, attempt: int, evidence_seal_ref: str | None) -> bool:
293
+ """Whether a closed attempt predates sealing: it has neither a seal nor its own event stream.
294
+
295
+ The sealing code writes the stream before it seals, so a failed seal leaves the stream behind
296
+ and is not mistaken for an attempt that was never observed at its close.
297
+ """
298
+ return evidence_seal_ref is None and not host_event_stream_path(prompt_path, attempt).is_file()
299
+
300
+
301
+ def seal_observed_attempt(
302
+ manifest_path: Path,
303
+ *,
304
+ invocation_ref: str,
305
+ attempt: int,
306
+ status: str,
307
+ change_summary: Mapping[str, Any],
308
+ artifact_paths: Sequence[Path],
309
+ prompt_path: Path,
310
+ task_key: str,
311
+ resume: bool = False,
312
+ ) -> AttemptEvidenceSeal | None:
313
+ """Record the terminal state okstra observed for an attempt and seal it with its results.
314
+
315
+ The closing call passes `resume=False`. A later identical close passes `resume=True`: it
316
+ finishes a seal whose stream this function already wrote, and seals nothing for an attempt
317
+ closed without one, because that attempt's bytes were never observed at its close.
318
+ Calling it again for the same attempt reuses the stream, so `finalize_attempt` returns the
319
+ existing seal rather than recording a second observation.
320
+ """
321
+ if resume and closed_before_sealing(prompt_path, attempt, None):
322
+ return None
323
+ stream = host_event_stream_path(prompt_path, attempt)
324
+ if not stream.is_file():
325
+ HostEventStreamWriter(stream, invocation_ref=invocation_ref, attempt=attempt).append(
326
+ "attempt-terminal-observed",
327
+ {"status": status, "artifacts": [str(path) for path in artifact_paths]},
328
+ )
329
+ changed = change_summary.get("changedPaths")
330
+ return finalize_attempt(
331
+ manifest_path,
332
+ build_dispatch_id(invocation_ref, attempt),
333
+ TerminalObservation(
334
+ status=status,
335
+ # A source-readonly attempt has no mutation snapshot; the empty digest records that no
336
+ # source state was observed for it.
337
+ source_diff_digest=str(change_summary.get("beforeDigest") or _sha(b"")),
338
+ git_projection_digest=str(change_summary.get("afterDigest") or _sha(b"")),
339
+ changed_paths=tuple(str(path) for path in changed) if isinstance(changed, list) else (),
340
+ artifact_paths=tuple(artifact_paths),
341
+ host_event_stream_path=stream,
342
+ ),
343
+ task_key=task_key,
344
+ )
345
+
346
+
347
+ def seal_or_report(manifest_path: Path, **observation: Any) -> bool:
348
+ """Seal an attempt; report a failure on stderr instead of replacing the caller's outcome.
349
+
350
+ The attempt is already closed when this runs, so the caller's own result or error is what its
351
+ user needs. Repeating the same close retries the seal.
352
+ """
353
+ try:
354
+ seal_observed_attempt(manifest_path, **observation)
355
+ except (OSError, ValueError) as exc:
356
+ print(
357
+ f"okstra dispatch: attempt {observation['invocation_ref']} #{observation['attempt']} "
358
+ f"was not sealed: {exc}; repeat the same close to retry",
359
+ file=sys.stderr,
360
+ )
361
+ return False
362
+ return True
363
+
287
364
  def reject_unsealed_attempt(
288
365
  manifest_path: Path,
289
366
  attempt_ref: str,
@@ -4,7 +4,7 @@ import json
4
4
  import re
5
5
  from pathlib import Path
6
6
  from collections.abc import Mapping
7
- from typing import Any
7
+ from typing import Any, Callable
8
8
 
9
9
  from .agent.invocation import (
10
10
  reserved_generation_reference, reserved_invocation_metadata_path, verify_agent_invocation,
@@ -15,13 +15,19 @@ from .execution_identity import ExecutionManifest
15
15
  from .execution_manifest import read_execution_manifest
16
16
  from .json_boundary import load_owned_object
17
17
  from .qa_procedures import canonical_json_digest, content_digest, safe_qa_path
18
- from .verification_dispatch import implementation_generation_frontier, read_completed_attempt_result, verification_generation_number
18
+ from .verification_dispatch import (
19
+ implementation_generation_frontier, read_completed_attempt_result, read_history_attempt_result,
20
+ verification_generation_number,
21
+ )
19
22
  from .verification_input_ref import VerificationInputReference
20
23
  from .verification_inputs import read_verification_inputs
21
24
  from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
22
25
  from .verification_invocation import VerificationGenerationReference, read_invocation_generation
23
26
  from .verification_evidence import implementation_verifier_roster, roster_verifier_role_execution_ref
24
27
 
28
+ # Reads an earlier attempt's result given its prompt path; the current verdict never uses one.
29
+ ResultReader = Callable[[Path, ExecutionManifest, str, int, Path], tuple[Path, bytes]]
30
+
25
31
 
26
32
  def design_review_required(project: Path, manifest: Mapping[str, Any]) -> bool:
27
33
  reference = VerificationInputReference.from_artifact_fields(manifest)
@@ -80,7 +86,8 @@ def _prior_reviews(
80
86
  if reference is None:
81
87
  raise ValueError("earlier design-review attempt has no bound generation")
82
88
  binding = BoundInvocation(invocation, number, index, None, reference.to_payload())
83
- record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt)
89
+ record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt,
90
+ read_result=read_history_attempt_result)
84
91
  history.append(record)
85
92
  return history
86
93
 
@@ -109,7 +116,7 @@ def prior_design_review_prompt(
109
116
 
110
117
  def _read_review(
111
118
  project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
112
- binding: BoundInvocation, attempt: int,
119
+ binding: BoundInvocation, attempt: int, *, read_result: ResultReader | None = None,
113
120
  ) -> tuple[dict[str, Any], str]:
114
121
  invocation = binding.invocation
115
122
  metadata_path = reserved_invocation_metadata_path(project, manifest, invocation.invocation_ref, attempt)
@@ -134,7 +141,11 @@ def _read_review(
134
141
  if (generation["generation"] != binding.generation_number
135
142
  or binding.generation_ref["path"] != expected_path.relative_to(project).as_posix()):
136
143
  raise ValueError("design review generation differs from its dispatch")
137
- result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
144
+ if read_result is None:
145
+ result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
146
+ else:
147
+ prompt = project / load_owned_object(metadata_path, artifact="invocation metadata")["prompt"]["path"]
148
+ result_path, raw = read_result(project, execution, invocation.invocation_ref, attempt, prompt)
138
149
  body = raw.decode("utf-8")
139
150
  source = Path(generation["sourceRoot"])
140
151
  review = parse_design_review(source if source.is_dir() else project, generation["designReview"], body)
@@ -450,7 +450,7 @@ def dispatch_plan(
450
450
  거부된 배치와 증거 보완으로 빠진 작업은 여기까지 오지 않으므로, 띄울 워커에
451
451
  대한 사실(체크포인트)은 이 시점에 기록해야 실제로 뜬 워커만 남는다.
452
452
  """
453
- plan = _recover_declaration_failures(plan)
453
+ plan = _route_closed_executors_to_evidence_recovery(plan)
454
454
  if not plan.jobs:
455
455
  return 0
456
456
  plan = _ensure_runtime_chain(plan)
@@ -555,7 +555,7 @@ def dispatch_cli_wrapper_plan(
555
555
  """Start one dependency-free CLI batch before collecting any worker."""
556
556
  if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
557
557
  raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
558
- plan = _recover_declaration_failures(plan)
558
+ plan = _route_closed_executors_to_evidence_recovery(plan)
559
559
  if not plan.jobs:
560
560
  return 0
561
561
  plan = _ensure_runtime_chain(plan)
@@ -1364,17 +1364,21 @@ def _spawn_cli_job_nonblocking(
1364
1364
  )
1365
1365
 
1366
1366
 
1367
- def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1368
- """선언만으로 거부된 구현은 같은 호출을 재시도하지 않고 증거 보완으로 연결한다."""
1367
+ def _route_closed_executors_to_evidence_recovery(plan: DispatchPlan) -> DispatchPlan:
1368
+ """Route a closed executor to evidence recovery instead of retrying the same invocation.
1369
+
1370
+ The causes are those `_evidence_recovery_source` selects.
1371
+ """
1369
1372
  if not any(job.has_execution_identity for job in plan.jobs):
1370
1373
  return plan
1371
1374
  manifest = read_execution_manifest(plan.manifest_path)
1372
1375
  jobs: list[WorkerJob] = []
1373
1376
  for job in plan.jobs:
1374
- source_attempt = _declaration_recovery_attempt(manifest, job)
1375
- if source_attempt is None:
1377
+ recovery = _evidence_recovery_source(manifest, plan.manifest, job)
1378
+ if recovery is None:
1376
1379
  jobs.append(job)
1377
1380
  continue
1381
+ source_attempt, reason = recovery
1378
1382
  recovered_ref = f"{job.invocation_ref}-evidence-recovery-{source_attempt}"
1379
1383
  recovered = [row for row in manifest.attempts if row.invocation_ref == recovered_ref]
1380
1384
  if recovered and max(recovered, key=lambda row: row.attempt).status == "ok":
@@ -1383,6 +1387,7 @@ def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1383
1387
  prepared, result = prepare_evidence_recovery(
1384
1388
  job.prompt_metadata_path, project_root=plan.project_root,
1385
1389
  result_path=job.result_path, source_attempt=source_attempt,
1390
+ reason=reason,
1386
1391
  )
1387
1392
  except AgentInvocationError as exc:
1388
1393
  raise DispatchError(f"evidence recovery could not be prepared: {exc}") from exc
@@ -1396,24 +1401,46 @@ def _recover_declaration_failures(plan: DispatchPlan) -> DispatchPlan:
1396
1401
  if not recovered:
1397
1402
  _append_event(plan, "worker-evidence-recovery-prepared", {
1398
1403
  "sourceInvocationRef": job.invocation_ref, "sourceAttempt": source_attempt,
1404
+ "reason": reason,
1399
1405
  "invocationRef": prepared.invocation_ref, "resultPath": str(result),
1400
1406
  "modelExecutionValue": job.model_execution_value,
1401
1407
  })
1402
1408
  return replace(plan, jobs=tuple(jobs))
1403
1409
 
1404
1410
 
1405
- def _declaration_recovery_attempt(manifest: ExecutionManifest, job: WorkerJob) -> int | None:
1406
- """선언 오류만 있는 종결 시도를 고르고 이미 시작한 후속 작업은 보존한다."""
1411
+ def _evidence_recovery_source(
1412
+ manifest: ExecutionManifest, run_manifest: Mapping[str, Any], job: WorkerJob,
1413
+ ) -> tuple[int, str] | None:
1414
+ """The executor attempt to route to evidence recovery and its cause; refuse when a later
1415
+ invocation of the same role already started.
1416
+
1417
+ `declaration`: rejected only for a declaration discrepancy. `unsealed`: closed ok before
1418
+ attempts were sealed. A run under the verification-evidence contract reads the executor result
1419
+ only through its seal (`verification_dispatch.read_completed_attempt_result`), so it needs a
1420
+ recovery result that does not repeat the implementation.
1421
+ """
1422
+ from .attempt_evidence import closed_before_sealing
1423
+ from .verification_invocation import verification_generation_required
1424
+
1407
1425
  prior = [row for row in manifest.attempts if row.invocation_ref == job.invocation_ref]
1408
1426
  last = max(prior, key=lambda row: row.attempt) if prior else None
1409
- summary = last.change_summary if last else {}
1410
- if not (
1411
- job.audience == "implementation-executor" and last is not None
1412
- and last.finished_at is not None and last.status == "contract-failed-unattributed"
1427
+ if (job.audience != "implementation-executor" or last is None or last.finished_at is None
1428
+ or "-evidence-recovery-" in job.invocation_ref):
1429
+ return None
1430
+ summary = last.change_summary
1431
+ if (
1432
+ last.status == "contract-failed-unattributed"
1413
1433
  and summary.get("sourceChanged") is False and summary.get("gitChanged") is False
1414
1434
  and summary.get("violations") == ["declared out-of-plan path did not change"]
1415
- and "-evidence-recovery-" not in job.invocation_ref
1416
1435
  ):
1436
+ reason = "declaration"
1437
+ elif (
1438
+ last.status == "ok"
1439
+ and closed_before_sealing(job.prompt_path, last.attempt, last.evidence_seal_ref)
1440
+ and verification_generation_required(run_manifest, "implementation-verifier")
1441
+ ):
1442
+ reason = "unsealed"
1443
+ else:
1417
1444
  return None
1418
1445
  recovered_ref = f"{job.invocation_ref}-evidence-recovery-{last.attempt}"
1419
1446
  later_refs = {
@@ -1429,7 +1456,7 @@ def _declaration_recovery_attempt(manifest: ExecutionManifest, job: WorkerJob) -
1429
1456
  f"{', '.join(sorted({row.invocation_ref for row in later}))} instead of redispatching "
1430
1457
  f"the historical failure {job.invocation_ref}"
1431
1458
  )
1432
- return last.attempt
1459
+ return last.attempt, reason
1433
1460
 
1434
1461
 
1435
1462
  def _next_attempt(plan: DispatchPlan, job: WorkerJob) -> int:
@@ -2305,6 +2332,8 @@ def _finish_manifest_attempt(
2305
2332
  and existing.result_path == expected_result
2306
2333
  and dict(existing.change_summary) == mutation.change_summary()
2307
2334
  ):
2335
+ if existing.evidence_seal_ref is None:
2336
+ _seal_finished_attempt(plan, job, attempt, mutation, resume=True)
2308
2337
  return
2309
2338
  raise DispatchError("attempt terminal mutation result drift")
2310
2339
  finish_attempt_mutation(
@@ -2321,33 +2350,24 @@ def _finish_manifest_attempt(
2321
2350
  _seal_finished_attempt(plan, job, attempt, mutation)
2322
2351
 
2323
2352
 
2324
- def _seal_finished_attempt(plan, job, attempt, mutation) -> None:
2325
- from .attempt_evidence import TerminalObservation, finalize_attempt
2353
+ def _seal_finished_attempt(plan, job, attempt, mutation, *, resume: bool = False) -> None:
2354
+ from .attempt_evidence import seal_or_report
2326
2355
 
2327
- events = job.prompt_path.with_name(job.prompt_path.name + ".host-events.jsonl")
2328
- if not events.is_file() or not job.has_execution_identity:
2356
+ if not job.has_execution_identity:
2329
2357
  return
2330
- artifacts = tuple(
2331
- path for path in (job.result_path, job.worker_result_path) if path
2358
+ seal_or_report(
2359
+ plan.manifest_path,
2360
+ invocation_ref=job.invocation_ref,
2361
+ attempt=attempt,
2362
+ status=mutation.status,
2363
+ change_summary=mutation.change_summary(),
2364
+ artifact_paths=tuple(
2365
+ path for path in (job.result_path, job.worker_result_path) if path
2366
+ ),
2367
+ prompt_path=job.prompt_path,
2368
+ task_key=_require_string(plan.manifest, "taskKey"),
2369
+ resume=resume,
2332
2370
  )
2333
- try:
2334
- finalize_attempt(
2335
- plan.manifest_path,
2336
- _build_dispatch_id(job.invocation_ref, attempt),
2337
- TerminalObservation(
2338
- status=mutation.status,
2339
- source_diff_digest=mutation.change_summary().get("beforeDigest", ""),
2340
- git_projection_digest=mutation.change_summary().get("afterDigest", ""),
2341
- changed_paths=tuple(mutation.changed_paths),
2342
- artifact_paths=artifacts,
2343
- host_event_stream_path=events,
2344
- project_root=plan.project_root,
2345
- worktree=Path(job.worktree_path) if job.worktree_path else None,
2346
- ),
2347
- task_key=_require_string(plan.manifest, "taskKey"),
2348
- )
2349
- except (OSError, ValueError):
2350
- return
2351
2371
 
2352
2372
 
2353
2373
  def _link_result(
@@ -1171,7 +1171,7 @@ def _finish_native_agent_attempt(
1171
1171
  result_path=result_path,
1172
1172
  policy=policy,
1173
1173
  )
1174
- _close_native_attempt(
1174
+ closed = _close_native_attempt(
1175
1175
  manifest_path,
1176
1176
  manifest,
1177
1177
  identity,
@@ -1179,6 +1179,17 @@ def _finish_native_agent_attempt(
1179
1179
  result_relative,
1180
1180
  summary,
1181
1181
  )
1182
+ _seal_native_attempt(
1183
+ project_root=project_root,
1184
+ manifest_path=manifest_path,
1185
+ manifest=manifest,
1186
+ dispatch=dispatch,
1187
+ identity=identity,
1188
+ status=status,
1189
+ result_relative=result_relative,
1190
+ summary=summary,
1191
+ resume=not closed,
1192
+ )
1182
1193
  if status != "ok":
1183
1194
  violations = summary.get("violations")
1184
1195
  detail = "; ".join(violations) if isinstance(violations, list) else status
@@ -1236,7 +1247,8 @@ def _close_native_attempt(
1236
1247
  status: str,
1237
1248
  result_path: str,
1238
1249
  summary: Mapping[str, Any],
1239
- ) -> None:
1250
+ ) -> bool:
1251
+ """Close the attempt; False when an identical earlier close already did."""
1240
1252
  execution = read_execution_manifest(manifest_path)
1241
1253
  existing = next(
1242
1254
  (
@@ -1252,7 +1264,7 @@ def _close_native_attempt(
1252
1264
  and existing.result_path == result_path
1253
1265
  and dict(existing.change_summary) == dict(summary)
1254
1266
  ):
1255
- return
1267
+ return False
1256
1268
  raise DispatchError("agent attempt terminal mutation result drift")
1257
1269
  finish_attempt_mutation(
1258
1270
  manifest_path,
@@ -1265,7 +1277,52 @@ def _close_native_attempt(
1265
1277
  change_summary=summary,
1266
1278
  task_key=require_string(manifest, "taskKey"),
1267
1279
  )
1280
+ return True
1281
+
1282
+
1283
+ def _seal_native_attempt(
1284
+ *,
1285
+ project_root: Path,
1286
+ manifest_path: Path,
1287
+ manifest: Mapping[str, Any],
1288
+ dispatch: Mapping[str, Any],
1289
+ identity: Mapping[str, Any],
1290
+ status: str,
1291
+ result_relative: str,
1292
+ summary: Mapping[str, Any],
1293
+ resume: bool,
1294
+ ) -> None:
1295
+ """Seal a host-native attempt with the same policy as `dispatch_core._seal_finished_attempt`.
1268
1296
 
1297
+ A verifier result in a run under the verification-evidence contract is read only through its
1298
+ seal (`verification_dispatch.read_completed_attempt_result`); without one the report cannot
1299
+ be assembled. `resume` is set when an earlier identical close already closed the attempt.
1300
+ """
1301
+ from .attempt_evidence import seal_or_report
1302
+
1303
+ if resume:
1304
+ execution = read_execution_manifest(manifest_path)
1305
+ attempt = next(
1306
+ (
1307
+ row for row in execution.attempts
1308
+ if row.invocation_ref == identity["invocation_ref"]
1309
+ and row.attempt == identity["attempt"]
1310
+ ),
1311
+ None,
1312
+ )
1313
+ if attempt is None or attempt.evidence_seal_ref is not None:
1314
+ return
1315
+ seal_or_report(
1316
+ manifest_path,
1317
+ invocation_ref=identity["invocation_ref"],
1318
+ attempt=identity["attempt"],
1319
+ status=status,
1320
+ change_summary=summary,
1321
+ artifact_paths=(project_root.resolve() / result_relative,),
1322
+ prompt_path=resolve_project_path(project_root, require_string(dispatch, "promptPath")),
1323
+ task_key=require_string(manifest, "taskKey"),
1324
+ resume=resume,
1325
+ )
1269
1326
 
1270
1327
  def _native_out_of_plan_paths(
1271
1328
  result_path: Path, *, project_root: Path
@@ -7,7 +7,7 @@ from typing import Any, Mapping
7
7
  from .correction_round import completed_round_attempts, correction_round
8
8
  from .execution_manifest import read_execution_manifest
9
9
  from .execution_identity import ExecutionManifest, build_dispatch_id
10
- from .attempt_evidence import AttemptEvidenceSeal, read_sealed_artifact
10
+ from .attempt_evidence import AttemptEvidenceSeal, closed_before_sealing, read_sealed_artifact
11
11
  from .json_boundary import ArtifactByteReader
12
12
  from .paths import RunRef
13
13
  from .qa_procedures import safe_qa_path
@@ -69,29 +69,51 @@ def implementation_generation_frontier(execution: ExecutionManifest) -> int | No
69
69
  if row.duty_id in ("implementation-executor", "implementation-verifier")), default=None)
70
70
 
71
71
 
72
- def read_completed_attempt_result(
72
+ def _completed_ok_result(
73
73
  project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int,
74
- *, reader: ArtifactByteReader | None = None,
75
- ) -> tuple[Path, bytes]:
74
+ ) -> tuple[Any, Path]:
75
+ """The completed ok attempt row and its result path, confined to project artifacts."""
76
76
  row = next((row for row in execution.attempts if (row.invocation_ref, row.attempt)
77
77
  == (invocation_ref, attempt)), None)
78
78
  if row is None or row.status != "ok" or row.finished_at is None or not row.result_path:
79
79
  raise ValueError("result requires the current completed ok attempt")
80
+ path = Path(row.result_path)
81
+ relative = path.relative_to(project).as_posix() if path.is_absolute() else path.as_posix()
82
+ if not relative.startswith(".okstra/"):
83
+ raise ValueError("result must remain in project artifacts")
84
+ return row, safe_qa_path(project, relative)
85
+
86
+
87
+ def read_completed_attempt_result(
88
+ project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int,
89
+ *, reader: ArtifactByteReader | None = None,
90
+ ) -> tuple[Path, bytes]:
91
+ row, path = _completed_ok_result(project, execution, invocation_ref, attempt)
80
92
  attempt_ref = build_dispatch_id(invocation_ref, attempt)
81
93
  seals = [seal for seal in execution.attempt_evidence_seals
82
94
  if seal.get("sealRef") == row.evidence_seal_ref and seal.get("attemptRef") == attempt_ref]
83
95
  if len(seals) != 1:
84
96
  raise ValueError("result requires its attempt evidence seal")
85
- path = Path(row.result_path)
86
- relative = path.relative_to(project).as_posix() if path.is_absolute() else path.as_posix()
87
- if not relative.startswith(".okstra/"):
88
- raise ValueError("result must remain in project artifacts")
89
- path = safe_qa_path(project, relative)
90
97
  seal = AttemptEvidenceSeal.from_payload(seals[0])
91
98
  raw = read_sealed_artifact(seal, path) if reader is None else read_sealed_artifact(seal, path, reader=reader)
92
99
  return path, raw
93
100
 
94
101
 
102
+ def read_history_attempt_result(
103
+ project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int, prompt_path: Path,
104
+ ) -> tuple[Path, bytes]:
105
+ """Read an earlier result for the prior-findings history.
106
+
107
+ A sealed attempt, or one whose seal failed after its stream was written, is read through its
108
+ seal. Only an attempt closed before sealing (`attempt_evidence.closed_before_sealing`) is read
109
+ directly, so its findings still reach the next verifier and the carry check. A current verdict
110
+ is read only through `read_completed_attempt_result`.
111
+ """
112
+ row, path = _completed_ok_result(project, execution, invocation_ref, attempt)
113
+ if not closed_before_sealing(prompt_path, attempt, row.evidence_seal_ref):
114
+ return read_completed_attempt_result(project, execution, invocation_ref, attempt)
115
+ return path, path.read_bytes()
116
+
95
117
  def _seal(
96
118
  project: Path, manifest_path: Path, manifest: Mapping[str, Any],
97
119
  active_context: Mapping[str, Any], *, audience: str, dispatch_kind: str,