okstra 0.229.0 → 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.
- package/README.md +1 -5
- package/dist/cli-registry.mjs +0 -18
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/lifecycle/doctor.mjs +0 -15
- package/dist/commands/lifecycle/doctor.mjs.map +1 -1
- package/dist/lib/skill-catalog.mjs +4 -4
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +105 -16
- package/docs/architecture.md +13 -14
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +11 -18
- package/package.json +1 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/prompts/launch.template.md +5 -5
- package/runtime/prompts/lead/convergence.md +4 -4
- package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
- package/runtime/prompts/lead/phase-routing.md +1 -1
- package/runtime/prompts/lead/report-writer.md +3 -3
- package/runtime/prompts/lead/team-contract.md +3 -3
- package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
- package/runtime/python/okstra_ctl/cmux.py +4 -2
- package/runtime/python/okstra_ctl/code_review_census.py +194 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
- package/runtime/python/okstra_ctl/code_review_target.py +38 -2
- package/runtime/python/okstra_ctl/conformance.py +30 -0
- package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
- package/runtime/python/okstra_ctl/correction_round.py +19 -13
- package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
- package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
- package/runtime/python/okstra_ctl/generated_input.py +21 -0
- package/runtime/python/okstra_ctl/ids.py +1 -41
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
- package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
- package/runtime/python/okstra_ctl/locks.py +28 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
- package/runtime/python/okstra_ctl/paths.py +75 -33
- package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
- package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
- package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
- package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
- package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
- package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
- package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
- package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
- package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
- package/runtime/python/okstra_ctl/process_group.py +26 -3
- package/runtime/python/okstra_ctl/qa_commands.py +5 -1
- package/runtime/python/okstra_ctl/recap.py +1 -2
- package/runtime/python/okstra_ctl/render.py +10 -2
- package/runtime/python/okstra_ctl/report_finalize.py +3 -3
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
- package/runtime/python/okstra_ctl/run.py +24 -20
- package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
- package/runtime/python/okstra_ctl/verification_capture.py +291 -0
- package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
- package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
- package/runtime/python/okstra_ctl/verification_generation.py +22 -12
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +73 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
- package/runtime/python/okstra_ctl/verification_target.py +10 -3
- package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
- package/runtime/python/okstra_ctl/wizard/render.py +2 -1
- package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
- package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
- package/runtime/python/okstra_ctl/worker_runner.py +1 -1
- package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
- package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
- package/runtime/skills/okstra-code-review/SKILL.md +7 -5
- package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
- package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +6 -6
- package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-setup/SKILL.md +2 -3
- package/runtime/validators/validate-run.py +110 -19
- package/docs/cli.md +0 -1060
- package/docs/container.md +0 -100
- package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
- package/docs/performance-improvement-plan-v2.md +0 -369
- package/runtime/python/okstra_ctl/container.py +0 -702
- package/runtime/python/okstra_ctl/rollup.py +0 -241
- package/runtime/python/okstra_ctl/usage_report.py +0 -362
- package/runtime/skills/okstra-container-build/SKILL.md +0 -139
- package/runtime/skills/okstra-inspect/SKILL.md +0 -100
- package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
- package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
- package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
- package/runtime/skills/okstra-inspect/facets/history.md +0 -86
- package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
- package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
- package/runtime/skills/okstra-inspect/facets/report.md +0 -57
- package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
- package/runtime/skills/okstra-inspect/facets/status.md +0 -163
- package/runtime/skills/okstra-inspect/facets/time.md +0 -57
- package/runtime/skills/okstra-rollup/SKILL.md +0 -75
- 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")
|