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,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 _OptionalVerificationPlan(TypedDict, total=False):
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(_OptionalVerificationPlan):
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 QA_COMMAND_EXECUTING_TASK_TYPES, validate_qa_commands
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, procedure_root,
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 (OSError, ValueError) as exc:
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
- with registry_lock(lock):
151
- if not path.exists():
152
- write_owned_object_atomic(
153
- path, payload, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
154
- validate_cross_fields=_verification_input_errors,
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
- snapshot = load_owned_object_snapshot(
157
- path, artifact=INPUT_ARTIFACT, schema=INPUT_SCHEMA,
158
- validate_cross_fields=_verification_input_errors,
159
- )
160
- if snapshot.value != payload:
161
- raise ValueError("verification input snapshot is immutable")
162
- return path, content_digest(snapshot.raw_bytes)
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
+ )