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.
- 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 +179 -13
- package/docs/architecture.md +13 -14
- package/docs/contributor-change-matrix.md +5 -5
- package/docs/project-structure-overview.md +16 -21
- package/package.json +1 -2
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/interactive.sh +2 -1
- package/runtime/bin/okstra-provider-exec.py +53 -4
- package/runtime/prompts/duties/code-reviewer.json +5 -2
- 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 +18 -5
- package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
- package/runtime/python/okstra_ctl/code_review_target.py +79 -25
- package/runtime/python/okstra_ctl/conformance.py +61 -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/execution_mutation_audit.py +100 -2
- 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 +17 -1
- package/runtime/python/okstra_ctl/paths.py +84 -31
- 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 +7 -2
- package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
- 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 +182 -0
- 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 +248 -0
- package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
- package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
- package/runtime/python/okstra_ctl/verification_target.py +20 -5
- 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 +84 -48
- package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
- package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
- 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 +118 -52
- 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,248 @@
|
|
|
1
|
+
"""Immutable source and inspection-file seals for verification generations."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from functools import partial
|
|
5
|
+
from itertools import pairwise
|
|
6
|
+
from pathlib import Path, PurePosixPath
|
|
7
|
+
from typing import Any, Literal, Mapping, TypedDict, cast
|
|
8
|
+
|
|
9
|
+
from okstra_project.dirs import OKSTRA_DIR_NAME
|
|
10
|
+
|
|
11
|
+
from .execution_mutation_audit import (
|
|
12
|
+
VerificationSourceSnapshot, capture_verification_source,
|
|
13
|
+
is_generated_verification_path,
|
|
14
|
+
)
|
|
15
|
+
from .json_boundary import load_owned_object_snapshot
|
|
16
|
+
from .paths import RunRef
|
|
17
|
+
from .qa_commands import (
|
|
18
|
+
QA_COMMAND_EXECUTING_TASK_TYPES, QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid,
|
|
19
|
+
)
|
|
20
|
+
from .qa_procedures import content_digest, existing_qa_file, safe_qa_path
|
|
21
|
+
from .verification_input_ref import VerificationInputReference
|
|
22
|
+
from .verification_conformance import capture_generation_conformance
|
|
23
|
+
from .verification_inputs import (
|
|
24
|
+
canonical_run_ref, publish_verification_snapshot, read_verification_inputs,
|
|
25
|
+
)
|
|
26
|
+
from .verification_target import read_verification_head
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class FrozenVerificationSource(TypedDict):
|
|
30
|
+
trackedPaths: list[str]
|
|
31
|
+
generatedRoots: list[str]
|
|
32
|
+
inputPaths: list[str]
|
|
33
|
+
protectedFiles: dict[str, str]
|
|
34
|
+
generatedFiles: dict[str, str]
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class _OptionalGenerationConformance(TypedDict, total=False):
|
|
38
|
+
conformanceStages: list[int]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class VerificationGenerationRecord(_OptionalGenerationConformance):
|
|
42
|
+
schemaVersion: Literal["1.0"]
|
|
43
|
+
kind: Literal["verification-generation"]
|
|
44
|
+
generation: int
|
|
45
|
+
taskType: str
|
|
46
|
+
runManifestPath: str
|
|
47
|
+
verificationInputsPath: str
|
|
48
|
+
verificationInputsDigest: str
|
|
49
|
+
head: str
|
|
50
|
+
sourceRoot: str
|
|
51
|
+
source: FrozenVerificationSource
|
|
52
|
+
artifactInputs: dict[str, str]
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
VERIFICATION_GENERATION_PATH_MAX_LENGTH = 4096
|
|
56
|
+
_DIGEST = {"type": "string", "pattern": f"^{QA_SOURCE_DIGEST_PATTERN.pattern}$"}
|
|
57
|
+
_PATH = {"type": "string", "minLength": 1,
|
|
58
|
+
"maxLength": VERIFICATION_GENERATION_PATH_MAX_LENGTH}
|
|
59
|
+
_PATHS = {"type": "array", "uniqueItems": True, "items": _PATH}
|
|
60
|
+
_FILES = {"type": "object", "additionalProperties": _DIGEST}
|
|
61
|
+
_SOURCE = {
|
|
62
|
+
"type": "object", "additionalProperties": False,
|
|
63
|
+
"required": ["trackedPaths", "generatedRoots", "inputPaths",
|
|
64
|
+
"protectedFiles", "generatedFiles"],
|
|
65
|
+
"properties": {
|
|
66
|
+
"trackedPaths": _PATHS, "generatedRoots": _PATHS, "inputPaths": _PATHS,
|
|
67
|
+
"protectedFiles": _FILES, "generatedFiles": _FILES,
|
|
68
|
+
},
|
|
69
|
+
}
|
|
70
|
+
_SCHEMA = {
|
|
71
|
+
"type": "object", "additionalProperties": False,
|
|
72
|
+
"required": list(VerificationGenerationRecord.__required_keys__),
|
|
73
|
+
"properties": {
|
|
74
|
+
"schemaVersion": {"const": "1.0"},
|
|
75
|
+
"kind": {"const": "verification-generation"},
|
|
76
|
+
"generation": {"type": "integer", "minimum": 1},
|
|
77
|
+
"taskType": {"enum": list(QA_COMMAND_EXECUTING_TASK_TYPES)},
|
|
78
|
+
"runManifestPath": _PATH, "verificationInputsPath": _PATH,
|
|
79
|
+
"verificationInputsDigest": _DIGEST,
|
|
80
|
+
"head": {"type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"},
|
|
81
|
+
"sourceRoot": _PATH, "source": _SOURCE, "artifactInputs": _FILES,
|
|
82
|
+
"conformanceStages": {"type": "array",
|
|
83
|
+
"items": {"type": "integer", "minimum": 1}},
|
|
84
|
+
},
|
|
85
|
+
}
|
|
86
|
+
_ARTIFACT = "verification generation"
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _generation_errors(payload: dict[str, Any]) -> list[str]:
|
|
90
|
+
stages = payload.get("conformanceStages", [])
|
|
91
|
+
if any(left >= right for left, right in pairwise(stages)):
|
|
92
|
+
return ["generation conformance stages must be strictly increasing"]
|
|
93
|
+
if not Path(payload["sourceRoot"]).is_absolute():
|
|
94
|
+
return ["generation source root must be absolute"]
|
|
95
|
+
source = payload["source"]
|
|
96
|
+
declarations = [*source["generatedRoots"], *source["inputPaths"],
|
|
97
|
+
*payload["artifactInputs"], payload["runManifestPath"],
|
|
98
|
+
payload["verificationInputsPath"]]
|
|
99
|
+
if any(not qa_relative_path_valid(path) for path in declarations):
|
|
100
|
+
return ["generation declarations require safe relative POSIX paths"]
|
|
101
|
+
for field in ("runManifestPath", "verificationInputsPath"):
|
|
102
|
+
if PurePosixPath(payload[field]).parts[0] != OKSTRA_DIR_NAME:
|
|
103
|
+
return ["generation references must remain in project artifacts"]
|
|
104
|
+
protected, generated = source["protectedFiles"], source["generatedFiles"]
|
|
105
|
+
paths = {*source["trackedPaths"], *protected, *generated, *declarations}
|
|
106
|
+
for relative in paths:
|
|
107
|
+
if len(relative) > VERIFICATION_GENERATION_PATH_MAX_LENGTH:
|
|
108
|
+
return ["generation source path is too long"]
|
|
109
|
+
path = PurePosixPath(relative)
|
|
110
|
+
if (not path.parts or path.is_absolute() or ".." in path.parts
|
|
111
|
+
or path.as_posix() != relative):
|
|
112
|
+
return ["generation source paths must be canonical and relative"]
|
|
113
|
+
if not set(source["inputPaths"]).issubset(protected):
|
|
114
|
+
return ["generation declared inputs must remain protected"]
|
|
115
|
+
roots = frozenset(source["generatedRoots"])
|
|
116
|
+
required = frozenset(source["trackedPaths"]) | frozenset(source["inputPaths"])
|
|
117
|
+
if any(is_generated_verification_path(path, roots, required) for path in protected):
|
|
118
|
+
return ["generation protected path conflicts with classification"]
|
|
119
|
+
if any(not is_generated_verification_path(path, roots, required)
|
|
120
|
+
for path in generated):
|
|
121
|
+
return ["generation output path conflicts with classification"]
|
|
122
|
+
return []
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _capture_generation_source(
|
|
126
|
+
project: Path, source_root: Path, *, source_inputs: frozenset[str],
|
|
127
|
+
generated_roots: frozenset[str], artifact_inputs: frozenset[str],
|
|
128
|
+
) -> tuple[VerificationSourceSnapshot, dict[str, str]]:
|
|
129
|
+
files = {existing_qa_file(project, path) for path in artifact_inputs}
|
|
130
|
+
if source_root == project:
|
|
131
|
+
source_inputs |= frozenset(
|
|
132
|
+
path.relative_to(project).as_posix() for path in files
|
|
133
|
+
)
|
|
134
|
+
snapshot = capture_verification_source(
|
|
135
|
+
source_root, generated_roots=generated_roots, input_paths=source_inputs,
|
|
136
|
+
)
|
|
137
|
+
artifacts = {}
|
|
138
|
+
for path in files:
|
|
139
|
+
relative = path.relative_to(project).as_posix()
|
|
140
|
+
artifacts[relative] = (
|
|
141
|
+
snapshot.protected_files[relative] if source_root == project
|
|
142
|
+
else content_digest(path.read_bytes())
|
|
143
|
+
)
|
|
144
|
+
return snapshot, artifacts
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def _capture_generation(
|
|
148
|
+
project: Path, ref: RunRef, reference: VerificationInputReference, *,
|
|
149
|
+
generation: int, expected_head: str, source_inputs: frozenset[str],
|
|
150
|
+
generated_roots: frozenset[str], artifact_inputs: frozenset[str],
|
|
151
|
+
changed_artifact_paths: frozenset[str], conformance_baseline: Mapping[int, str],
|
|
152
|
+
) -> VerificationGenerationRecord:
|
|
153
|
+
inputs = read_verification_inputs(
|
|
154
|
+
safe_qa_path(project, reference.relative_path), reference.digest,
|
|
155
|
+
)
|
|
156
|
+
source_root = Path(inputs["sourceRoot"])
|
|
157
|
+
head = read_verification_head(source_root, expected_head)
|
|
158
|
+
conformance = None
|
|
159
|
+
if "approvedPlan" in inputs:
|
|
160
|
+
conformance = capture_generation_conformance(
|
|
161
|
+
project, ref, inputs["approvedPlan"], changed_artifact_paths,
|
|
162
|
+
conformance_baseline,
|
|
163
|
+
)
|
|
164
|
+
artifact_inputs |= conformance.artifact_paths
|
|
165
|
+
snapshot, artifacts = _capture_generation_source(
|
|
166
|
+
project, source_root, generated_roots=generated_roots,
|
|
167
|
+
source_inputs=source_inputs,
|
|
168
|
+
artifact_inputs=artifact_inputs,
|
|
169
|
+
)
|
|
170
|
+
if conformance is not None and conformance.manifest is not None:
|
|
171
|
+
relative, digest = conformance.manifest
|
|
172
|
+
if artifacts[relative] != digest:
|
|
173
|
+
raise ValueError("verification conformance manifest changed during capture")
|
|
174
|
+
read_verification_head(source_root, head)
|
|
175
|
+
return {
|
|
176
|
+
"schemaVersion": "1.0", "kind": "verification-generation",
|
|
177
|
+
"generation": generation, "taskType": ref.task_type,
|
|
178
|
+
"runManifestPath": ref.manifest.relative_to(project).as_posix(),
|
|
179
|
+
**reference.to_artifact_fields(), "head": head,
|
|
180
|
+
"sourceRoot": str(snapshot.root),
|
|
181
|
+
"source": {
|
|
182
|
+
"trackedPaths": sorted(snapshot.tracked_paths),
|
|
183
|
+
"generatedRoots": sorted(snapshot.generated_roots),
|
|
184
|
+
"inputPaths": sorted(snapshot.input_paths),
|
|
185
|
+
"protectedFiles": dict(snapshot.protected_files),
|
|
186
|
+
"generatedFiles": dict(snapshot.generated_files),
|
|
187
|
+
},
|
|
188
|
+
"artifactInputs": artifacts,
|
|
189
|
+
**({"conformanceStages": list(conformance.stages)}
|
|
190
|
+
if conformance is not None else {}),
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def prepare_verification_generation(
|
|
195
|
+
project: Path, ref: RunRef, reference: VerificationInputReference, *,
|
|
196
|
+
generation: int, expected_head: str, source_inputs: frozenset[str],
|
|
197
|
+
generated_roots: frozenset[str], artifact_inputs: frozenset[str],
|
|
198
|
+
changed_artifact_paths: frozenset[str], conformance_baseline: Mapping[int, str],
|
|
199
|
+
) -> tuple[Path, str]:
|
|
200
|
+
if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
|
|
201
|
+
raise ValueError("verification generations require a QA-executing phase")
|
|
202
|
+
ref = canonical_run_ref(project, ref)
|
|
203
|
+
project = project.resolve()
|
|
204
|
+
input_path = ref.verification_inputs.relative_to(project).as_posix()
|
|
205
|
+
if reference.relative_path != input_path:
|
|
206
|
+
raise ValueError("generation input reference belongs to a different run")
|
|
207
|
+
return publish_verification_snapshot(
|
|
208
|
+
project, ref.verification_generation(generation),
|
|
209
|
+
capture=partial(
|
|
210
|
+
_capture_generation, project, ref, reference, generation=generation,
|
|
211
|
+
expected_head=expected_head, source_inputs=source_inputs,
|
|
212
|
+
generated_roots=generated_roots, artifact_inputs=artifact_inputs,
|
|
213
|
+
changed_artifact_paths=changed_artifact_paths,
|
|
214
|
+
conformance_baseline=conformance_baseline,
|
|
215
|
+
),
|
|
216
|
+
artifact=_ARTIFACT, schema=_SCHEMA,
|
|
217
|
+
validate_cross_fields=_generation_errors, comparison_key=_generation_identity,
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _generation_identity(payload: Mapping[str, Any]) -> dict[str, Any]:
|
|
222
|
+
return {**payload, "source": {**payload["source"], "generatedFiles": {}}}
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def sealed_source_snapshot(
|
|
226
|
+
record: VerificationGenerationRecord,
|
|
227
|
+
) -> VerificationSourceSnapshot:
|
|
228
|
+
source = record["source"]
|
|
229
|
+
return VerificationSourceSnapshot(
|
|
230
|
+
root=Path(record["sourceRoot"]),
|
|
231
|
+
tracked_paths=frozenset(source["trackedPaths"]),
|
|
232
|
+
generated_roots=frozenset(source["generatedRoots"]),
|
|
233
|
+
input_paths=frozenset(source["inputPaths"]),
|
|
234
|
+
protected_files=source["protectedFiles"],
|
|
235
|
+
generated_files=source["generatedFiles"],
|
|
236
|
+
)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def read_verification_generation(
|
|
240
|
+
path: Path, expected_digest: str,
|
|
241
|
+
) -> VerificationGenerationRecord:
|
|
242
|
+
stored = load_owned_object_snapshot(
|
|
243
|
+
path, artifact=_ARTIFACT, schema=_SCHEMA,
|
|
244
|
+
validate_cross_fields=_generation_errors,
|
|
245
|
+
)
|
|
246
|
+
if content_digest(stored.raw_bytes) != expected_digest:
|
|
247
|
+
raise ValueError("verification generation digest mismatch")
|
|
248
|
+
return cast(VerificationGenerationRecord, stored.value)
|
|
@@ -25,6 +25,15 @@ class VerificationInputReference:
|
|
|
25
25
|
) -> VerificationInputReference | None:
|
|
26
26
|
return cls._read(payload, _ARTIFACT_PATH, _ARTIFACT_DIGEST)
|
|
27
27
|
|
|
28
|
+
@classmethod
|
|
29
|
+
def required_from_artifact_fields(
|
|
30
|
+
cls, payload: Mapping[str, object],
|
|
31
|
+
) -> VerificationInputReference:
|
|
32
|
+
reference = cls.from_artifact_fields(payload)
|
|
33
|
+
if reference is None:
|
|
34
|
+
raise ValueError("run manifest has no verification input reference")
|
|
35
|
+
return reference
|
|
36
|
+
|
|
28
37
|
@classmethod
|
|
29
38
|
def from_context(
|
|
30
39
|
cls, context: Mapping[str, object],
|
|
@@ -12,6 +12,24 @@ class FrozenProcedure(TypedDict):
|
|
|
12
12
|
digest: str
|
|
13
13
|
|
|
14
14
|
|
|
15
|
+
QaSourceStatus = Literal[
|
|
16
|
+
"not-declared", "not-queried", "no-baseline", "unchanged", "changed",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class _OptionalQaSourceObservation(TypedDict, total=False):
|
|
21
|
+
observedSourceDigest: str
|
|
22
|
+
error: str
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class QaSourceObservation(_OptionalQaSourceObservation):
|
|
26
|
+
sourceStatus: QaSourceStatus
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class FrozenQaSourceObservation(QaSourceObservation):
|
|
30
|
+
entryDigest: str
|
|
31
|
+
|
|
32
|
+
|
|
15
33
|
class FrozenVerificationPlan(TypedDict):
|
|
16
34
|
path: str
|
|
17
35
|
digest: str
|
|
@@ -20,11 +38,14 @@ class FrozenVerificationPlan(TypedDict):
|
|
|
20
38
|
conformance: list[dict[str, Any]]
|
|
21
39
|
|
|
22
40
|
|
|
23
|
-
class
|
|
41
|
+
class _OptionalVerificationInputs(TypedDict, total=False):
|
|
24
42
|
approvedPlan: FrozenVerificationPlan
|
|
43
|
+
qaSourceObservations: dict[str, list[FrozenQaSourceObservation]]
|
|
44
|
+
conformanceBaseline: dict[str, str]
|
|
45
|
+
conformanceBaselineError: str
|
|
25
46
|
|
|
26
47
|
|
|
27
|
-
class VerificationInputs(
|
|
48
|
+
class VerificationInputs(_OptionalVerificationInputs):
|
|
28
49
|
schemaVersion: Literal["1.0", "2.0"]
|
|
29
50
|
kind: Literal["verification-inputs"]
|
|
30
51
|
sourceRoot: str
|
|
@@ -1,16 +1,22 @@
|
|
|
1
1
|
"""Preparation must allow inspection scripts that implementation creates later."""
|
|
2
2
|
from __future__ import annotations
|
|
3
3
|
|
|
4
|
+
from dataclasses import replace
|
|
5
|
+
from functools import partial
|
|
4
6
|
from pathlib import Path
|
|
5
|
-
from typing import Any, Mapping, cast
|
|
7
|
+
from typing import Any, Callable, Mapping, cast
|
|
6
8
|
|
|
7
9
|
from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
|
|
8
10
|
|
|
9
11
|
from .json_boundary import load_owned_object_snapshot, write_owned_object_atomic
|
|
10
12
|
from .paths import RunRef
|
|
11
|
-
from .qa_commands import
|
|
13
|
+
from .qa_commands import (
|
|
14
|
+
QA_COMMAND_EXECUTING_TASK_TYPES, QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid,
|
|
15
|
+
validate_qa_commands,
|
|
16
|
+
)
|
|
12
17
|
from .qa_procedures import (
|
|
13
|
-
content_digest, existing_qa_file, load_qa_config,
|
|
18
|
+
canonical_json_digest, content_digest, existing_qa_file, load_qa_config,
|
|
19
|
+
new_qa_source_digest_reader, observe_qa_sources, procedure_root, qa_source_status,
|
|
14
20
|
read_validated_procedure, safe_qa_path, validate_procedure_sections,
|
|
15
21
|
)
|
|
16
22
|
|
|
@@ -18,6 +24,7 @@ from .verification_input_types import (
|
|
|
18
24
|
INPUT_KIND, INPUT_SCHEMA_VERSION, PLAN_INPUT_SCHEMA_VERSION,
|
|
19
25
|
FrozenProcedure, VerificationInputs,
|
|
20
26
|
)
|
|
27
|
+
from .verification_conformance import capture_conformance_baseline
|
|
21
28
|
from .verification_plan import (
|
|
22
29
|
VERIFICATION_PLAN_SCHEMA, capture_verification_plan, verification_plan_errors,
|
|
23
30
|
)
|
|
@@ -40,6 +47,11 @@ INPUT_SCHEMA = {
|
|
|
40
47
|
"qaCommands": {"type": "object"},
|
|
41
48
|
"procedures": {"type": "object"},
|
|
42
49
|
"approvedPlan": VERIFICATION_PLAN_SCHEMA,
|
|
50
|
+
"qaSourceObservations": {"type": "object"},
|
|
51
|
+
"conformanceBaseline": {
|
|
52
|
+
"type": "object", "additionalProperties": {"type": "string"},
|
|
53
|
+
},
|
|
54
|
+
"conformanceBaselineError": {"type": "string", "minLength": 1},
|
|
43
55
|
},
|
|
44
56
|
}
|
|
45
57
|
|
|
@@ -53,6 +65,41 @@ def _procedure_paths(commands: Mapping[str, list[dict[str, Any]]]) -> tuple[str,
|
|
|
53
65
|
))
|
|
54
66
|
|
|
55
67
|
|
|
68
|
+
def _verification_source_errors(
|
|
69
|
+
commands: dict[str, list[dict[str, Any]]], observations: dict[str, Any],
|
|
70
|
+
) -> list[str]:
|
|
71
|
+
if set(observations) != set(commands):
|
|
72
|
+
return ["source observation categories must match qaCommands"]
|
|
73
|
+
required = {"entryDigest", "sourceStatus"}
|
|
74
|
+
allowed = required | {"observedSourceDigest", "error"}
|
|
75
|
+
for category, entries in commands.items():
|
|
76
|
+
rows = observations[category]
|
|
77
|
+
if not isinstance(rows, list) or len(rows) != len(entries):
|
|
78
|
+
return ["source observation rows must match qaCommands"]
|
|
79
|
+
for entry, row in zip(entries, rows):
|
|
80
|
+
if (not isinstance(row, dict) or not required.issubset(row)
|
|
81
|
+
or set(row).difference(allowed)
|
|
82
|
+
or not all(isinstance(value, str) for value in row.values())):
|
|
83
|
+
return ["invalid source observation fields"]
|
|
84
|
+
if row["entryDigest"] != canonical_json_digest(entry):
|
|
85
|
+
return ["source observation declaration digest mismatch"]
|
|
86
|
+
observed = row.get("observedSourceDigest")
|
|
87
|
+
if observed is not None and not QA_SOURCE_DIGEST_PATTERN.fullmatch(
|
|
88
|
+
observed,
|
|
89
|
+
):
|
|
90
|
+
return ["invalid source observation digest"]
|
|
91
|
+
has_sources = bool(entry.get("sourcePaths"))
|
|
92
|
+
if observed is not None and (not has_sources or "error" in row):
|
|
93
|
+
return ["source observation digest conflicts with its declaration"]
|
|
94
|
+
if observed is None and has_sources and not row.get("error", "").strip():
|
|
95
|
+
return ["unavailable source observation requires an error"]
|
|
96
|
+
if not has_sources and "error" in row:
|
|
97
|
+
return ["undeclared source observation must not contain an error"]
|
|
98
|
+
if row["sourceStatus"] != qa_source_status(entry, observed):
|
|
99
|
+
return ["source observation status is inconsistent"]
|
|
100
|
+
return []
|
|
101
|
+
|
|
102
|
+
|
|
56
103
|
def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
|
|
57
104
|
has_plan = "approvedPlan" in payload
|
|
58
105
|
if payload["schemaVersion"] == PLAN_INPUT_SCHEMA_VERSION and not has_plan:
|
|
@@ -91,13 +138,37 @@ def _verification_input_errors(payload: dict[str, Any]) -> list[str]:
|
|
|
91
138
|
continue
|
|
92
139
|
if content_digest(raw) != procedure["digest"]:
|
|
93
140
|
errors.append(f"frozen procedure digest mismatch: {relative}")
|
|
141
|
+
if "qaSourceObservations" in payload:
|
|
142
|
+
errors.extend(_verification_source_errors(
|
|
143
|
+
commands, payload["qaSourceObservations"],
|
|
144
|
+
))
|
|
145
|
+
if "conformanceBaseline" in payload or "conformanceBaselineError" in payload:
|
|
146
|
+
errors.extend(_conformance_baseline_errors(payload))
|
|
94
147
|
return errors
|
|
95
148
|
|
|
96
149
|
|
|
150
|
+
def _conformance_baseline_errors(payload: Mapping[str, Any]) -> list[str]:
|
|
151
|
+
plan = payload.get("approvedPlan")
|
|
152
|
+
if plan is None:
|
|
153
|
+
return ["conformance baseline requires approvedPlan"]
|
|
154
|
+
if "conformanceBaselineError" in payload:
|
|
155
|
+
if "conformanceBaseline" in payload:
|
|
156
|
+
return ["conformance baseline and its capture error are exclusive"]
|
|
157
|
+
return []
|
|
158
|
+
baseline = payload["conformanceBaseline"]
|
|
159
|
+
declared = {str(row["stage"]) for row in plan["conformance"]}
|
|
160
|
+
if any(stage not in declared for stage in baseline):
|
|
161
|
+
return ["conformance baseline has an undeclared stage"]
|
|
162
|
+
if any(not qa_relative_path_valid(path) for path in baseline.values()):
|
|
163
|
+
return ["conformance baseline requires safe relative POSIX paths"]
|
|
164
|
+
return []
|
|
165
|
+
|
|
166
|
+
|
|
97
167
|
def capture_verification_inputs(
|
|
98
168
|
project: Path, source: Path, *, approved_plan: Path | None = None,
|
|
99
169
|
) -> VerificationInputs:
|
|
100
170
|
declared = load_qa_config(project).get("qaCommands") or {}
|
|
171
|
+
read_digest = new_qa_source_digest_reader()
|
|
101
172
|
commands = {
|
|
102
173
|
category: [{key: entry[key] for key in QA_INPUT_FIELDS if key in entry}
|
|
103
174
|
for entry in entries]
|
|
@@ -108,7 +179,7 @@ def capture_verification_inputs(
|
|
|
108
179
|
root = procedure_root(project, source, relative)
|
|
109
180
|
try:
|
|
110
181
|
raw = read_validated_procedure(existing_qa_file(root, relative))
|
|
111
|
-
except
|
|
182
|
+
except ValueError as exc:
|
|
112
183
|
raise ValueError(f"verification procedure {relative}: {exc}") from exc
|
|
113
184
|
procedures[relative] = {
|
|
114
185
|
"body": raw.decode("utf-8"), "digest": content_digest(raw),
|
|
@@ -117,6 +188,12 @@ def capture_verification_inputs(
|
|
|
117
188
|
"schemaVersion": INPUT_SCHEMA_VERSION, "kind": INPUT_KIND,
|
|
118
189
|
"sourceRoot": str(source.resolve()), "qaCommands": commands,
|
|
119
190
|
"procedures": procedures,
|
|
191
|
+
"qaSourceObservations": {
|
|
192
|
+
category: [{**observe_qa_sources(source, entry, read_digest),
|
|
193
|
+
"entryDigest": canonical_json_digest(entry)}
|
|
194
|
+
for entry in entries]
|
|
195
|
+
for category, entries in commands.items()
|
|
196
|
+
},
|
|
120
197
|
}
|
|
121
198
|
if approved_plan is not None:
|
|
122
199
|
payload["schemaVersion"] = PLAN_INPUT_SCHEMA_VERSION
|
|
@@ -134,29 +211,90 @@ def read_verification_inputs(path: Path, expected_digest: str) -> VerificationIn
|
|
|
134
211
|
return cast(VerificationInputs, snapshot.value)
|
|
135
212
|
|
|
136
213
|
|
|
214
|
+
def publish_verification_snapshot(
|
|
215
|
+
project: Path, destination: Path, *,
|
|
216
|
+
capture: Callable[[], Mapping[str, Any]], artifact: str,
|
|
217
|
+
schema: Mapping[str, Any],
|
|
218
|
+
validate_cross_fields: Callable[[dict[str, Any]], list[str]],
|
|
219
|
+
comparison_key: Callable[[Mapping[str, Any]], object],
|
|
220
|
+
) -> tuple[Path, str]:
|
|
221
|
+
project = project.absolute()
|
|
222
|
+
destination = destination.absolute()
|
|
223
|
+
if not destination.is_relative_to(project / OKSTRA_DIR_NAME):
|
|
224
|
+
raise ValueError(f"{artifact} must remain in project artifacts")
|
|
225
|
+
relative = destination.relative_to(project).as_posix()
|
|
226
|
+
safe_qa_path(project, relative)
|
|
227
|
+
lock = safe_qa_path(project, json_lock_path(Path(relative)).as_posix())
|
|
228
|
+
with registry_lock(lock):
|
|
229
|
+
path = safe_qa_path(project, relative)
|
|
230
|
+
payload = dict(capture())
|
|
231
|
+
if not path.exists():
|
|
232
|
+
write_owned_object_atomic(
|
|
233
|
+
path, payload, artifact=artifact, schema=schema,
|
|
234
|
+
validate_cross_fields=validate_cross_fields,
|
|
235
|
+
)
|
|
236
|
+
stored = load_owned_object_snapshot(
|
|
237
|
+
path, artifact=artifact, schema=schema,
|
|
238
|
+
validate_cross_fields=validate_cross_fields,
|
|
239
|
+
)
|
|
240
|
+
if comparison_key(stored.value) != comparison_key(payload):
|
|
241
|
+
raise ValueError(f"{artifact} is immutable")
|
|
242
|
+
return path, content_digest(stored.raw_bytes)
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def conformance_baseline_required(
|
|
246
|
+
task_type: str, inputs: Mapping[str, Any],
|
|
247
|
+
) -> bool:
|
|
248
|
+
return task_type == "implementation" and "approvedPlan" in inputs
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def frozen_conformance_baseline(
|
|
252
|
+
inputs: VerificationInputs, task_type: str,
|
|
253
|
+
) -> dict[int, str]:
|
|
254
|
+
if not conformance_baseline_required(task_type, inputs):
|
|
255
|
+
return {}
|
|
256
|
+
if "conformanceBaseline" not in inputs:
|
|
257
|
+
cause = inputs.get(
|
|
258
|
+
"conformanceBaselineError", "no capture error was recorded",
|
|
259
|
+
)
|
|
260
|
+
raise ValueError(f"verification inputs carry no conformance baseline: {cause}")
|
|
261
|
+
return {
|
|
262
|
+
int(stage): script
|
|
263
|
+
for stage, script in inputs["conformanceBaseline"].items()
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def canonical_run_ref(project: Path, ref: RunRef) -> RunRef:
|
|
268
|
+
reference_root = ref.project_root or project
|
|
269
|
+
if reference_root.resolve() != project.resolve():
|
|
270
|
+
raise ValueError("verification run project root mismatch")
|
|
271
|
+
relative_task = ref.task_root.absolute().relative_to(reference_root.absolute())
|
|
272
|
+
return replace(
|
|
273
|
+
ref,
|
|
274
|
+
task_root_override=safe_qa_path(project.resolve(), relative_task.as_posix()),
|
|
275
|
+
)
|
|
276
|
+
|
|
277
|
+
|
|
137
278
|
def prepare_verification_inputs(
|
|
138
279
|
project: Path, source: Path, ref: RunRef, *, approved_plan: Path | None = None,
|
|
139
280
|
) -> tuple[Path, str]:
|
|
140
281
|
if ref.task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
|
|
141
282
|
raise ValueError("verification inputs require a QA-executing phase")
|
|
142
|
-
destination = ref.verification_inputs.absolute()
|
|
143
|
-
project_root = project.absolute()
|
|
144
|
-
if not destination.is_relative_to(project_root / OKSTRA_DIR_NAME):
|
|
145
|
-
raise ValueError("verification inputs must remain in the project artifact tree")
|
|
146
|
-
artifact_relative = destination.relative_to(project_root)
|
|
147
|
-
path = safe_qa_path(project, artifact_relative.as_posix())
|
|
148
|
-
lock = safe_qa_path(project, json_lock_path(artifact_relative).as_posix())
|
|
149
283
|
payload = capture_verification_inputs(project, source, approved_plan=approved_plan)
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
284
|
+
if conformance_baseline_required(ref.task_type, payload):
|
|
285
|
+
# The executor may rename or delete an earlier stage's script; only the
|
|
286
|
+
# manifest as it stood before implementation can still name the old path.
|
|
287
|
+
task_root = canonical_run_ref(project, ref).task_root
|
|
288
|
+
try:
|
|
289
|
+
payload["conformanceBaseline"] = capture_conformance_baseline(
|
|
290
|
+
project.resolve(), task_root, payload["approvedPlan"],
|
|
155
291
|
)
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
292
|
+
except ValueError as exc:
|
|
293
|
+
# Runs without the evidence contract keep preparing over a malformed
|
|
294
|
+
# manifest; the recorded cause lets a marked seal refuse it by name.
|
|
295
|
+
payload["conformanceBaselineError"] = str(exc)
|
|
296
|
+
return publish_verification_snapshot(
|
|
297
|
+
project, ref.verification_inputs, capture=partial(dict, payload),
|
|
298
|
+
artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
|
|
299
|
+
validate_cross_fields=_verification_input_errors, comparison_key=dict,
|
|
300
|
+
)
|