okstra 0.228.2 → 0.230.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.
Files changed (124) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -0,0 +1,652 @@
1
+ """Evidence mode: run one frozen check for one open verifier attempt."""
2
+ from __future__ import annotations
3
+
4
+ import contextlib
5
+ import itertools
6
+ import os
7
+ import signal
8
+ import subprocess
9
+ from dataclasses import dataclass
10
+ from datetime import datetime, timezone
11
+ from pathlib import Path
12
+ from typing import Any, Callable, Literal, Mapping, TypedDict, cast
13
+
14
+ from .agent.invocation import (
15
+ AgentInvocationError, InvocationMetadataIdentity, agent_model_assignment_from_payload,
16
+ invocation_execution_identity_from_manifest, invocation_metadata_identity,
17
+ metadata_generation_reference, verify_agent_invocation,
18
+ )
19
+ from .conformance import validate_conformance_manifest
20
+ from .execution_manifest import read_execution_manifest
21
+ from .execution_mutation_audit import (
22
+ VerificationSourceSnapshot, capture_verification_source,
23
+ compare_verification_sources,
24
+ )
25
+ from .json_boundary import (
26
+ JsonBoundaryError, load_owned_object, load_owned_object_snapshot,
27
+ write_owned_object_atomic,
28
+ )
29
+ from .locks import resource_exec_lock, worktree_exec_lock
30
+ from .paths import RunRef
31
+ from .ports.verification_inputs import VerificationInputStore
32
+ from .qa_commands import (
33
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE, split_verification_command,
34
+ verification_command_defects,
35
+ )
36
+ from .qa_procedures import content_digest, existing_qa_file, safe_qa_path
37
+ from .verification_conformance import conformance_manifest_path, conformance_stage
38
+ from .verification_capture import (
39
+ CLEANUP_GRACE_SECONDS, DRAIN_AFTER_EXIT_SECONDS, CommandCapture, StreamCapture,
40
+ run_captured,
41
+ )
42
+ from .verification_generation import (
43
+ VerificationGenerationRecord, sealed_source_snapshot,
44
+ )
45
+ from .verification_invocation import (
46
+ VerificationGenerationReference, read_invocation_generation,
47
+ )
48
+ from .verification_target import read_verification_head
49
+ from .worker_prompt_policy import stage_qa_owner
50
+
51
+ EVIDENCE_INCOMPLETE_EXIT = 70
52
+ # A failed observation, unlike a ValueError mismatch, says nothing about the target.
53
+ _OBSERVATION_ERRORS = (OSError, subprocess.SubprocessError)
54
+ _STRINGS = {"type": "array", "items": {"type": "string"}}
55
+ _TEXT, _OPTIONAL_TEXT = {"type": "string"}, {"type": ["string", "null"]}
56
+ _COUNT = {"type": "integer", "minimum": 1}
57
+
58
+
59
+ def _object(nullable: bool, **properties: Mapping[str, Any]) -> dict[str, Any]:
60
+ return {"type": ["object", "null"] if nullable else "object",
61
+ "additionalProperties": False, "required": list(properties),
62
+ "properties": properties}
63
+
64
+
65
+ _STREAM = _object(True, path=_TEXT, bytes={"type": "integer", "minimum": 0},
66
+ digest=_TEXT, saved={"type": "boolean"},
67
+ forwardError=_OPTIONAL_TEXT)
68
+ _TARGET = _object(True, protectedChanges=_STRINGS, generatedChanges=_STRINGS,
69
+ unclassifiedPaths=_STRINGS, trackedPathsChanged={"type": "boolean"},
70
+ artifactInputChanges=_STRINGS)
71
+ _RECORD_SCHEMA = _object(
72
+ False, schemaVersion={"const": "1.0"}, kind={"const": "verification-execution"},
73
+ status={"enum": ["started", "completed", "output-save-failed",
74
+ "drain-incomplete", "cleanup-unconfirmed", "target-changed",
75
+ "lock-unavailable", "cancelled", "interrupted",
76
+ "evidence-error"]},
77
+ runManifestPath=_TEXT, verificationGeneration=_object(False, path=_TEXT,
78
+ digest=_TEXT),
79
+ generation=_COUNT, participantRef=_TEXT, roleExecutionRef=_TEXT,
80
+ invocationRef=_TEXT, attempt=_COUNT, audience=_TEXT, checkRef=_TEXT,
81
+ checkRun=_COUNT, verificationInputsPath=_TEXT, verificationInputsDigest=_TEXT,
82
+ resourceKeys=_STRINGS, worktree=_TEXT, expectedHead=_TEXT,
83
+ declaredCommand=_TEXT, command=_TEXT, argv=_STRINGS,
84
+ locks={"enum": ["not-acquired", "held"]},
85
+ policy=_object(False, drainAfterExitSeconds={"type": "number"},
86
+ cleanupGraceSeconds={"type": "number"}),
87
+ startedAt=_OPTIONAL_TEXT, finishedAt=_OPTIONAL_TEXT,
88
+ exitCode={"type": ["integer", "null"]}, signal=_OPTIONAL_TEXT,
89
+ drain={"enum": ["not-run", "complete", "incomplete"]},
90
+ cleanup={"enum": ["not-run", "confirmed", "unconfirmed"]},
91
+ stdout=_STREAM, stderr=_STREAM, targetBefore=_TARGET, targetAfter=_TARGET,
92
+ error=_OPTIONAL_TEXT,
93
+ )
94
+
95
+
96
+ class _StreamRecord(TypedDict):
97
+ path: str
98
+ bytes: int
99
+ digest: str
100
+ saved: bool
101
+ forwardError: str | None
102
+
103
+
104
+ class _TargetRecord(TypedDict):
105
+ protectedChanges: list[str]
106
+ generatedChanges: list[str]
107
+ unclassifiedPaths: list[str]
108
+ trackedPathsChanged: bool
109
+ artifactInputChanges: list[str]
110
+
111
+
112
+ class _PolicyRecord(TypedDict):
113
+ drainAfterExitSeconds: float
114
+ cleanupGraceSeconds: float
115
+
116
+
117
+ class VerificationExecutionRecord(TypedDict):
118
+ schemaVersion: Literal["1.0"]
119
+ kind: Literal["verification-execution"]
120
+ status: str
121
+ runManifestPath: str
122
+ verificationGeneration: dict[str, str]
123
+ generation: int
124
+ participantRef: str
125
+ roleExecutionRef: str
126
+ invocationRef: str
127
+ attempt: int
128
+ audience: str
129
+ checkRef: str
130
+ checkRun: int
131
+ verificationInputsPath: str
132
+ verificationInputsDigest: str
133
+ resourceKeys: list[str]
134
+ worktree: str
135
+ expectedHead: str
136
+ declaredCommand: str
137
+ command: str
138
+ argv: list[str]
139
+ locks: Literal["not-acquired", "held"]
140
+ policy: _PolicyRecord
141
+ startedAt: str | None
142
+ finishedAt: str | None
143
+ exitCode: int | None
144
+ signal: str | None
145
+ drain: Literal["not-run", "complete", "incomplete"]
146
+ cleanup: str
147
+ stdout: _StreamRecord | None
148
+ stderr: _StreamRecord | None
149
+ targetBefore: _TargetRecord | None
150
+ targetAfter: _TargetRecord | None
151
+ error: str | None
152
+
153
+
154
+ def shell_argv(command: str) -> list[str]:
155
+ return [os.environ.get("SHELL", "") or "/bin/sh", "-c", command]
156
+
157
+
158
+ def shell_exit_code(returncode: int) -> int:
159
+ # A child killed by signal N reports -N; a shell reports that death as 128+N.
160
+ return 128 - returncode if returncode < 0 else returncode
161
+
162
+
163
+ class EvidenceRefused(ValueError):
164
+ """The invocation or check cannot produce evidence; nothing was run."""
165
+
166
+
167
+ @dataclass(frozen=True)
168
+ class EvidenceCheck:
169
+ project: Path
170
+ run_ref: RunRef
171
+ identity: InvocationMetadataIdentity
172
+ audience: str
173
+ generation_ref: VerificationGenerationReference
174
+ generation: VerificationGenerationRecord
175
+ check_ref: str
176
+ declared_command: str
177
+ command: str
178
+ resource_keys: tuple[str, ...]
179
+
180
+ @property
181
+ def worktree(self) -> Path:
182
+ return Path(self.generation["sourceRoot"])
183
+
184
+
185
+ def resolve_evidence_check(
186
+ project: Path, metadata_path: Path, check_ref: str, *,
187
+ store: VerificationInputStore,
188
+ ) -> EvidenceCheck:
189
+ try:
190
+ return _resolve(project.resolve(), metadata_path.resolve(), check_ref, store)
191
+ except EvidenceRefused:
192
+ raise
193
+ except (AgentInvocationError, OSError, ValueError, KeyError) as exc:
194
+ raise EvidenceRefused(str(exc)) from exc
195
+
196
+
197
+ def _resolve(
198
+ project: Path, metadata_path: Path, check_ref: str, store: VerificationInputStore,
199
+ ) -> EvidenceCheck:
200
+ metadata = load_owned_object(metadata_path, artifact="agent invocation metadata")
201
+ identity = invocation_metadata_identity(metadata)
202
+ if identity is None or metadata["invocationId"] != identity.invocation_ref:
203
+ raise EvidenceRefused("evidence mode requires a v2 invocation identity")
204
+ manifest_path = safe_qa_path(project, metadata["contractSource"]["runManifestPath"])
205
+ errors = verify_agent_invocation(
206
+ metadata_path, project_root=project, expected_run_manifest_path=manifest_path,
207
+ expected_invocation_ref=identity.invocation_ref,
208
+ )
209
+ if errors:
210
+ raise EvidenceRefused("invocation verification failed: " + "; ".join(errors))
211
+ manifest = load_owned_object(manifest_path, artifact="run manifest")
212
+ reference = metadata_generation_reference(metadata)
213
+ generation = read_invocation_generation(
214
+ project, manifest_path, manifest, reference, metadata["audience"],
215
+ )
216
+ if generation is None or reference is None:
217
+ raise EvidenceRefused(
218
+ "evidence mode requires a verifier bound to a verification generation"
219
+ )
220
+ if identity.duty_id != metadata["audience"]:
221
+ raise EvidenceRefused("invocation duty does not own verifier checks")
222
+ _require_open_attempt(manifest_path, identity)
223
+ run_ref = RunRef.from_manifest(manifest_path, manifest)
224
+ # The check's directory segment must be a safe path segment before anything runs.
225
+ run_ref.verification_check_dir(identity.invocation_ref, identity.attempt, check_ref)
226
+ declared, resource_keys = _declared_check(
227
+ project, run_ref, manifest, generation, identity, check_ref, store,
228
+ )
229
+ command, _ = split_verification_command(declared)
230
+ defects = verification_command_defects(command)
231
+ if defects:
232
+ raise EvidenceRefused("; ".join(defects))
233
+ return EvidenceCheck(
234
+ project, run_ref, identity, metadata["audience"], reference, generation,
235
+ check_ref, declared, command, resource_keys,
236
+ )
237
+
238
+
239
+ def _declared_check(
240
+ project: Path, run_ref: RunRef, manifest: Mapping[str, Any],
241
+ generation: VerificationGenerationRecord, identity: InvocationMetadataIdentity,
242
+ check_ref: str, store: VerificationInputStore,
243
+ ) -> tuple[str, tuple[str, ...]]:
244
+ """The declared command and resource keys of a qa or conformance check."""
245
+ kind, _, identifier = check_ref.partition(":")
246
+ if kind == "conformance" and identifier:
247
+ if conformance_check_owner_ref(manifest) not in (
248
+ None, identity.role_execution_ref,
249
+ ):
250
+ raise EvidenceRefused(
251
+ "only the stage QA owner runs an implementation conformance check"
252
+ )
253
+ entry = _sealed_conformance_entry(
254
+ project, run_ref, generation, check_ref, identifier,
255
+ )
256
+ return entry["runCommand"], ()
257
+ entry = _frozen_check(project, generation, check_ref, store)
258
+ return entry["cmd"], tuple(sorted(entry.get("resourceKeys", ())))
259
+
260
+
261
+ def conformance_check_owner_ref(manifest: Mapping[str, Any]) -> str | None:
262
+ """The one role execution whose conformance runs count in an implementation
263
+ run, the stage QA owner's; None in final verification, where every
264
+ verifier's do."""
265
+ if manifest.get("taskType") != "implementation":
266
+ return None
267
+ return _stage_qa_owner_role_execution_ref(manifest)
268
+
269
+
270
+ def _stage_qa_owner_role_execution_ref(manifest: Mapping[str, Any]) -> str:
271
+ """The role execution of the stage QA owner, resolved the way initial
272
+ materialization binds a roster worker to its role execution."""
273
+ owner = stage_qa_owner(manifest)
274
+ if not owner:
275
+ raise EvidenceRefused("the run roster has no stage QA owner")
276
+ assignment_ref = f"initial/{owner}"
277
+ assignments = manifest.get("invocationAssignments")
278
+ identity = invocation_execution_identity_from_manifest(
279
+ manifest,
280
+ assignment=agent_model_assignment_from_payload(
281
+ assignments.get(assignment_ref) if isinstance(assignments, Mapping)
282
+ else None
283
+ ),
284
+ assignment_ref=assignment_ref,
285
+ duty_id=QA_VERIFIER_AUDIENCE_BY_TASK_TYPE["implementation"],
286
+ )
287
+ if identity is None:
288
+ raise EvidenceRefused("the stage QA owner has no v2 role execution")
289
+ return identity.role_execution_ref
290
+
291
+
292
+ def _sealed_conformance_entry(
293
+ project: Path, ref: RunRef, generation: VerificationGenerationRecord,
294
+ check_ref: str, stage_key: str,
295
+ ) -> Mapping[str, Any]:
296
+ relative = conformance_manifest_path(project, ref.task_root)
297
+ sealed = generation["artifactInputs"].get(relative)
298
+ if sealed is None:
299
+ raise EvidenceRefused("the verification generation seals no conformance manifest")
300
+ stored = load_owned_object_snapshot(
301
+ existing_qa_file(project, relative), artifact="conformance manifest",
302
+ )
303
+ if content_digest(stored.raw_bytes) != sealed:
304
+ raise EvidenceRefused(
305
+ "the conformance manifest changed after the generation was sealed"
306
+ )
307
+ conformance_manifest = stored.value
308
+ errors = validate_conformance_manifest(conformance_manifest)
309
+ if errors:
310
+ raise EvidenceRefused("; ".join(errors))
311
+ entry = next((entry for entry in conformance_manifest["entries"]
312
+ if entry["stageKey"] == stage_key), None)
313
+ if entry is None:
314
+ raise EvidenceRefused(f"{check_ref} is not a sealed conformance entry")
315
+ if conformance_stage(stage_key) not in generation.get("conformanceStages", ()):
316
+ raise EvidenceRefused(f"{check_ref} is not a conformance stage of this generation")
317
+ return entry
318
+
319
+
320
+ def _require_open_attempt(
321
+ manifest_path: Path, identity: InvocationMetadataIdentity,
322
+ ) -> None:
323
+ execution = read_execution_manifest(manifest_path)
324
+ expected = (identity.invocation_ref, identity.participant_ref,
325
+ identity.role_execution_ref, identity.duty_id)
326
+ if not any((row.invocation_ref, row.participant_ref, row.role_execution_ref,
327
+ row.duty_id) == expected for row in execution.invocations):
328
+ raise EvidenceRefused("invocation is not in the run execution identity")
329
+ latest = max((row for row in execution.attempts
330
+ if row.invocation_ref == identity.invocation_ref),
331
+ key=lambda row: row.attempt, default=None)
332
+ if (latest is None or latest.attempt != identity.attempt
333
+ or latest.finished_at is not None):
334
+ raise EvidenceRefused("invocation attempt is not open: finished or replaced")
335
+
336
+
337
+ def _frozen_check(
338
+ project: Path, generation: VerificationGenerationRecord, check_ref: str,
339
+ store: VerificationInputStore,
340
+ ) -> Mapping[str, Any]:
341
+ kind, _, identifier = check_ref.partition(":")
342
+ if kind != "qa" or not identifier:
343
+ raise EvidenceRefused(
344
+ "check reference must be qa:<qaCommands id> or conformance:<stageKey>"
345
+ )
346
+ inputs = store.read(
347
+ safe_qa_path(project, generation["verificationInputsPath"]),
348
+ generation["verificationInputsDigest"],
349
+ )
350
+ matches = [entry for entries in inputs["qaCommands"].values()
351
+ for entry in entries if entry.get("id") == identifier]
352
+ if len(matches) != 1:
353
+ raise EvidenceRefused(f"{check_ref} is not a frozen check of this generation")
354
+ return matches[0]
355
+
356
+
357
+ class _Interrupted(Exception):
358
+ def __init__(self, signum: int) -> None:
359
+ super().__init__(signal.Signals(signum).name)
360
+ self.signum = signum
361
+
362
+
363
+ class _Abandoned(Exception):
364
+ def __init__(self, status: str, error: str | None) -> None:
365
+ super().__init__(error)
366
+ self.status = status
367
+ self.error = error
368
+
369
+
370
+ class _InterruptGuard:
371
+ """Raise while waiting for locks; only flag once the command runs, so the
372
+ capture loop can stop the group, drain and publish before exiting."""
373
+
374
+ def __init__(self) -> None:
375
+ self.signum: int | None = None
376
+ self.capturing = False
377
+
378
+ def __enter__(self) -> _InterruptGuard:
379
+ self._previous = {
380
+ sig: signal.signal(sig, self._handle)
381
+ for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP)
382
+ }
383
+ return self
384
+
385
+ def __exit__(self, *_: object) -> None:
386
+ for sig, handler in self._previous.items():
387
+ signal.signal(sig, handler)
388
+
389
+ def _handle(self, signum: int, _frame: object) -> None:
390
+ if self.signum is None:
391
+ self.signum = signum
392
+ if not self.capturing:
393
+ raise _Interrupted(signum)
394
+
395
+
396
+ def run_evidence_check(
397
+ check: EvidenceCheck, metadata_path: Path, *, store: VerificationInputStore,
398
+ home: Path, on_wait: Callable[[Path], None], notify: Callable[[str], None],
399
+ ) -> int:
400
+ try:
401
+ check_run_dir, check_run = _allocate_check_run(check)
402
+ except OSError as exc:
403
+ notify(f"evidence record was not created ({exc})")
404
+ return EVIDENCE_INCOMPLETE_EXIT
405
+ record = _initial_record(check, check_run)
406
+ with _InterruptGuard() as guard, contextlib.ExitStack() as locks:
407
+
408
+ def finish(status: str, error: str | None, exit_code: int | None) -> int:
409
+ # A signal while the record is published must not abandon it.
410
+ guard.capturing = True
411
+ code = _finish(record, check_run_dir, notify, status, error, exit_code)
412
+ return code if guard.signum is None else 128 + guard.signum
413
+
414
+ try:
415
+ before = _lock_and_recheck(
416
+ check, metadata_path, store, home, on_wait, locks, record,
417
+ )
418
+ capture = _start_capture(check, check_run_dir, record, guard)
419
+ except _Abandoned as exc:
420
+ return finish(exc.status, exc.error, None)
421
+ except _Interrupted as exc:
422
+ return finish("interrupted", str(exc), None)
423
+ except (OSError, JsonBoundaryError, subprocess.SubprocessError) as exc:
424
+ return finish("evidence-error", str(exc), None)
425
+ return _conclude(record, check, capture, before, finish)
426
+
427
+
428
+ def _lock_and_recheck(
429
+ check: EvidenceCheck, metadata_path: Path, store: VerificationInputStore,
430
+ home: Path, on_wait: Callable[[Path], None], locks: contextlib.ExitStack,
431
+ record: VerificationExecutionRecord,
432
+ ) -> VerificationSourceSnapshot:
433
+ try:
434
+ locks.enter_context(worktree_exec_lock(home, check.worktree, on_wait=on_wait))
435
+ for key in check.resource_keys:
436
+ locks.enter_context(resource_exec_lock(home, key, on_wait=on_wait))
437
+ except OSError as exc:
438
+ raise _Abandoned("lock-unavailable", str(exc)) from exc
439
+ record["locks"] = "held"
440
+ try:
441
+ current = resolve_evidence_check(
442
+ check.project, metadata_path, check.check_ref, store=store,
443
+ )
444
+ except EvidenceRefused as exc:
445
+ raise _Abandoned("cancelled", str(exc)) from exc
446
+ if current != check:
447
+ raise _Abandoned("cancelled", "invocation changed while waiting")
448
+ try:
449
+ before, record["targetBefore"] = _observe_target(check, None)
450
+ except ValueError as exc:
451
+ raise _Abandoned("target-changed", str(exc)) from exc
452
+ if not _target_clean(record["targetBefore"]):
453
+ raise _Abandoned("target-changed", None)
454
+ return before
455
+
456
+
457
+ def _start_capture(
458
+ check: EvidenceCheck, check_run_dir: Path, record: VerificationExecutionRecord,
459
+ guard: _InterruptGuard,
460
+ ) -> CommandCapture:
461
+ record.update(status="started", startedAt=_now())
462
+ _publish(check_run_dir, record)
463
+ guard.capturing = True
464
+ return run_captured(
465
+ record["argv"], check.worktree, stdout_path=check_run_dir / "stdout.log",
466
+ stderr_path=check_run_dir / "stderr.log",
467
+ stop_requested=lambda: guard.signum is not None,
468
+ )
469
+
470
+
471
+ def _conclude(
472
+ record: VerificationExecutionRecord, check: EvidenceCheck,
473
+ capture: CommandCapture, before: VerificationSourceSnapshot,
474
+ finish: Callable[[str, str | None, int | None], int],
475
+ ) -> int:
476
+ error = _record_capture(record, check, capture)
477
+ observed = True
478
+ try:
479
+ _, record["targetAfter"] = _observe_target(check, before)
480
+ except ValueError as exc:
481
+ error = error or str(exc)
482
+ except _OBSERVATION_ERRORS as exc:
483
+ error, observed = error or str(exc), False
484
+ status = _capture_status(capture, record["targetAfter"], observed=observed)
485
+ return finish(status, error, (shell_exit_code(capture.returncode)
486
+ if status == "completed" else None))
487
+
488
+
489
+ def _allocate_check_run(check: EvidenceCheck) -> tuple[Path, int]:
490
+ for check_run in itertools.count(1):
491
+ path = check.run_ref.verification_execution_dir(
492
+ check.identity.invocation_ref, check.identity.attempt, check.check_ref,
493
+ check_run,
494
+ )
495
+ try:
496
+ path.mkdir(parents=True)
497
+ except FileExistsError:
498
+ # expected-miss: an earlier run of this check owns that number;
499
+ # reruns never overwrite it.
500
+ continue
501
+ return path, check_run
502
+ raise AssertionError("unreachable")
503
+
504
+
505
+ def _initial_record(
506
+ check: EvidenceCheck, check_run: int,
507
+ ) -> VerificationExecutionRecord:
508
+ generation, identity = check.generation, check.identity
509
+ return {
510
+ "schemaVersion": "1.0", "kind": "verification-execution",
511
+ "status": "lock-unavailable", "runManifestPath": generation["runManifestPath"],
512
+ "verificationGeneration": check.generation_ref.to_payload(),
513
+ "generation": generation["generation"],
514
+ "participantRef": identity.participant_ref,
515
+ "roleExecutionRef": identity.role_execution_ref,
516
+ "invocationRef": identity.invocation_ref, "attempt": identity.attempt,
517
+ "audience": check.audience, "checkRef": check.check_ref, "checkRun": check_run,
518
+ "verificationInputsPath": generation["verificationInputsPath"],
519
+ "verificationInputsDigest": generation["verificationInputsDigest"],
520
+ "resourceKeys": list(check.resource_keys),
521
+ "worktree": generation["sourceRoot"], "expectedHead": generation["head"],
522
+ "declaredCommand": check.declared_command, "command": check.command,
523
+ "argv": shell_argv(check.command),
524
+ "locks": "not-acquired",
525
+ "policy": {"drainAfterExitSeconds": DRAIN_AFTER_EXIT_SECONDS,
526
+ "cleanupGraceSeconds": CLEANUP_GRACE_SECONDS},
527
+ "startedAt": None, "finishedAt": None, "exitCode": None, "signal": None,
528
+ "drain": "not-run", "cleanup": "not-run", "stdout": None, "stderr": None,
529
+ "targetBefore": None, "targetAfter": None, "error": None,
530
+ }
531
+
532
+
533
+ def _observe_target(
534
+ check: EvidenceCheck, previous: VerificationSourceSnapshot | None,
535
+ ) -> tuple[VerificationSourceSnapshot, _TargetRecord]:
536
+ """Protected inputs compare with the seal; generated outputs with the
537
+ previous observation, so an earlier check's report is not this one's."""
538
+ sealed = sealed_source_snapshot(check.generation)
539
+ if previous is None:
540
+ previous = sealed
541
+ read_verification_head(check.worktree, check.generation["head"])
542
+ current = capture_verification_source(
543
+ check.worktree, generated_roots=sealed.generated_roots,
544
+ input_paths=sealed.input_paths,
545
+ )
546
+ changes = compare_verification_sources(sealed, current)
547
+ artifacts = sorted(
548
+ relative for relative, digest in check.generation["artifactInputs"].items()
549
+ if content_digest(existing_qa_file(check.project, relative).read_bytes())
550
+ != digest
551
+ )
552
+ return current, {
553
+ "protectedChanges": list(changes.protected_changes),
554
+ "generatedChanges": list(
555
+ compare_verification_sources(previous, current).generated_changes
556
+ ),
557
+ "unclassifiedPaths": list(changes.unclassified_paths),
558
+ "trackedPathsChanged": changes.tracked_paths_changed,
559
+ "artifactInputChanges": artifacts,
560
+ }
561
+
562
+
563
+ def _target_clean(target: _TargetRecord | None) -> bool:
564
+ return target is not None and not (
565
+ target["protectedChanges"] or target["unclassifiedPaths"]
566
+ or target["trackedPathsChanged"] or target["artifactInputChanges"]
567
+ )
568
+
569
+
570
+ def _record_capture(
571
+ record: VerificationExecutionRecord, check: EvidenceCheck, capture: CommandCapture,
572
+ ) -> str | None:
573
+ code = capture.returncode
574
+ record.update(
575
+ exitCode=code if code >= 0 else None,
576
+ signal=signal.Signals(-code).name if code < 0 else None,
577
+ drain="complete" if capture.drain_complete else "incomplete",
578
+ cleanup=capture.cleanup,
579
+ stdout=_stream_record(check.project, capture.stdout),
580
+ stderr=_stream_record(check.project, capture.stderr),
581
+ )
582
+ return capture.stdout.save_error or capture.stderr.save_error
583
+
584
+
585
+ def _stream_record(project: Path, stream: StreamCapture) -> _StreamRecord:
586
+ return {"path": stream.path.relative_to(project).as_posix(),
587
+ "bytes": stream.bytes, "digest": stream.digest,
588
+ "saved": stream.save_error is None, "forwardError": stream.forward_error}
589
+
590
+
591
+ def _capture_status(
592
+ capture: CommandCapture, target: _TargetRecord | None, *, observed: bool,
593
+ ) -> str:
594
+ if capture.interrupted:
595
+ return "interrupted"
596
+ if capture.stdout.save_error or capture.stderr.save_error:
597
+ return "output-save-failed"
598
+ if not capture.drain_complete:
599
+ return "drain-incomplete"
600
+ if capture.cleanup == "unconfirmed":
601
+ return "cleanup-unconfirmed"
602
+ if not observed:
603
+ return "evidence-error"
604
+ return "completed" if _target_clean(target) else "target-changed"
605
+
606
+
607
+ def _finish(
608
+ record: VerificationExecutionRecord, check_run_dir: Path,
609
+ notify: Callable[[str], None], status: str, error: str | None,
610
+ exit_code: int | None,
611
+ ) -> int:
612
+ record.update(status=status, finishedAt=_now(), error=error)
613
+ path = check_run_dir / "record.json"
614
+ try:
615
+ _publish(check_run_dir, record)
616
+ except (OSError, JsonBoundaryError) as exc:
617
+ notify(f"evidence record was not published ({exc}): {path}")
618
+ return EVIDENCE_INCOMPLETE_EXIT
619
+ notify(f"evidence {status}: {path}" + (f" ({error})" if error else ""))
620
+ return EVIDENCE_INCOMPLETE_EXIT if exit_code is None else exit_code
621
+
622
+
623
+ def _publish(check_run_dir: Path, record: VerificationExecutionRecord) -> None:
624
+ write_owned_object_atomic(
625
+ check_run_dir / "record.json", record, artifact="verification execution record",
626
+ schema=_RECORD_SCHEMA, validate_cross_fields=_record_errors,
627
+ )
628
+
629
+
630
+ def read_verification_execution_record(path: Path) -> VerificationExecutionRecord:
631
+ return cast(VerificationExecutionRecord, load_owned_object(
632
+ path, artifact="verification execution record", schema=_RECORD_SCHEMA,
633
+ validate_cross_fields=_record_errors,
634
+ ))
635
+
636
+
637
+ def _record_errors(record: dict[str, Any]) -> list[str]:
638
+ if record["status"] != "completed":
639
+ return []
640
+ streams_saved = all(stream and stream["saved"]
641
+ for stream in (record["stdout"], record["stderr"]))
642
+ one_outcome = (record["exitCode"] is None) != (record["signal"] is None)
643
+ process_settled = (record["drain"] == "complete"
644
+ and record["cleanup"] == "confirmed")
645
+ if (streams_saved and one_outcome and process_settled
646
+ and record["locks"] == "held" and _target_clean(record["targetAfter"])):
647
+ return []
648
+ return ["a completed verification execution requires complete evidence"]
649
+
650
+
651
+ def _now() -> str:
652
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")