okstra 0.234.1 → 0.236.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 (171) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +7 -3
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +64 -44
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/host-registry-client.d.mts +9 -2
  25. package/dist/lib/host-registry-client.mjs +29 -3
  26. package/dist/lib/host-registry-client.mjs.map +1 -1
  27. package/dist/lib/python-helper.d.mts +1 -1
  28. package/dist/lib/python-helper.mjs +11 -5
  29. package/dist/lib/python-helper.mjs.map +1 -1
  30. package/dist/lib/runtime-payload.mjs +1 -0
  31. package/dist/lib/runtime-payload.mjs.map +1 -1
  32. package/dist/lib/types.d.mts +1 -0
  33. package/docs/architecture/storage-model.md +50 -0
  34. package/docs/architecture.md +1 -1
  35. package/docs/cli.md +37 -15
  36. package/docs/project-structure-overview.md +6 -1
  37. package/package.json +1 -1
  38. package/runtime/BUILD.json +2 -2
  39. package/runtime/agents/operations/trace-tests-review.json +6 -0
  40. package/runtime/bin/lib/okstra/usage.sh +8 -8
  41. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  42. package/runtime/prompts/duties/test-reviewer.json +32 -0
  43. package/runtime/prompts/lead/convergence.md +4 -1
  44. package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
  45. package/runtime/prompts/lead/report-writer.md +13 -1
  46. package/runtime/prompts/profiles/_common-contract.md +10 -1
  47. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  48. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  49. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  50. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  51. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  52. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  53. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  54. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  55. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  56. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  57. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  58. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  59. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  60. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  61. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  62. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  63. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  64. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  65. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  66. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  67. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  68. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  69. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  70. package/runtime/python/okstra_ctl/consumers.py +6 -1
  71. package/runtime/python/okstra_ctl/convergence.py +95 -5
  72. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  73. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  74. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  75. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  76. package/runtime/python/okstra_ctl/design_review.py +6 -26
  77. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  78. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  79. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  80. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  81. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  82. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  83. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  84. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  85. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  86. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  87. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  88. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  89. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  90. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  91. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  92. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  93. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  94. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  95. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  96. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  97. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  98. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  99. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  100. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  101. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  102. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  103. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  104. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  105. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  106. package/runtime/python/okstra_ctl/models.py +2 -2
  107. package/runtime/python/okstra_ctl/paths.py +7 -4
  108. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  109. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  110. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  111. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  112. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  113. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  114. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  115. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  116. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  117. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  118. package/runtime/python/okstra_ctl/render.py +4 -0
  119. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  120. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  121. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  122. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  123. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  124. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  125. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  126. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  127. package/runtime/python/okstra_ctl/run.py +17 -1
  128. package/runtime/python/okstra_ctl/run_context.py +18 -3
  129. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  130. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  131. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  132. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  133. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  134. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  135. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  136. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  137. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  138. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  139. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  140. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  141. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  142. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  143. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  144. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  145. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  146. package/runtime/python/okstra_ctl/wizard/state.py +67 -20
  147. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  148. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  149. package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
  150. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  151. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  152. package/runtime/python/okstra_token_usage/claude.py +5 -1
  153. package/runtime/python/okstra_token_usage/collect.py +3 -3
  154. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  155. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  156. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  157. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  158. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  159. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  160. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  161. package/runtime/skills/okstra-run/SKILL.md +33 -2
  162. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  163. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  164. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  165. package/runtime/templates/reports/html/i18n/en.json +113 -0
  166. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  167. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  168. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  169. package/runtime/templates/trace/trace.template.md +2 -0
  170. package/runtime/templates/worker-prompt-preamble.md +12 -2
  171. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,208 @@
1
+ """Bind existing runner observations to an owner's preserved implementation target."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from itertools import islice
6
+ import os
7
+ from pathlib import Path
8
+ import tempfile
9
+ from typing import Any, Iterator, Mapping
10
+
11
+ from ..execution_mutation_audit import VerificationSourceSnapshot, compare_verification_sources, is_generated_verification_path
12
+ from ..implementation_generation_evidence import read_settled_implementation_generation
13
+ from ..json_boundary import PageBudgetExhausted, ReadBudget
14
+ from ..qa_procedures import project_artifact_relative_path, safe_qa_path
15
+ from ..report_execution_evidence import collect_report_evidence_snapshot, output_tail
16
+ from ..verification_generation import VerificationGenerationRecord, sealed_source_snapshot
17
+ from .baseline import ComparisonError, ComparisonOwner
18
+ from .inputs import _ChangedInput, _artifact_bytes
19
+ from .model import MAX_COMPARISON_READ_BYTES, MAX_RECORDS, RunEvidenceSelection
20
+ from .source import MAX_PATHS, collect_source, digest_bytes
21
+ from .target import GENERATION_PATTERN
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class RunEvidence:
26
+ generation: str | None
27
+ source_root: str | None
28
+ rows: tuple[dict[str, Any], ...]
29
+ selection: RunEvidenceSelection
30
+ limitations: tuple[str, ...]
31
+ target_limitations: tuple[str, ...] = ()
32
+
33
+
34
+ def _bare_digest(value: str) -> str:
35
+ bare = value.removeprefix("sha256:")
36
+ if not value.startswith("sha256:") or not GENERATION_PATTERN.fullmatch(bare):
37
+ raise ComparisonError("Execution evidence digest is invalid")
38
+ return bare
39
+
40
+
41
+ def _merge_fingerprints(target: dict[str, str | None], observed: Mapping[str, str | None]) -> None:
42
+ for path, digest in observed.items():
43
+ bare = None if digest is None else _bare_digest(digest)
44
+ if path in target and target[path] != bare:
45
+ raise _ChangedInput(f"Execution evidence input changed during assembly: {path}")
46
+ target[path] = bare
47
+
48
+
49
+ def _target_limitations(target: Mapping[str, Any] | None, generation: VerificationGenerationRecord, token: str) -> list[str]:
50
+ if target is None:
51
+ return ["The current verification generation has no preserved target"]
52
+ limitations = []
53
+ for key, expected in (("generation", token), ("sourceRoot", generation["sourceRoot"]), ("head", generation["head"])):
54
+ if target.get(key) != expected:
55
+ limitations.append(f"Preserved target {key} differs from the current verification generation")
56
+ if target.get("status") != "complete" or target.get("completeInventory") is not True:
57
+ limitations.append("Preserved target source inventory is incomplete")
58
+ sealed = sealed_source_snapshot(generation)
59
+ protected: dict[str, str] = {}
60
+ generated: dict[str, str] = {}
61
+ tracked = set()
62
+ for row in target.get("files", []):
63
+ path = row["path"]
64
+ if row.get("tracked"):
65
+ tracked.add(path)
66
+ if row.get("status") == "missing":
67
+ continue
68
+ digest = row.get("digest")
69
+ if row.get("status") != "complete" or not isinstance(digest, str) or not GENERATION_PATTERN.fullmatch(digest):
70
+ limitations.append(f"Preserved source identity is unavailable: {path}")
71
+ continue
72
+ bucket = generated if is_generated_verification_path(path, sealed.generated_roots | sealed.ignored_roots, sealed.tracked_paths | sealed.input_paths) else protected
73
+ bucket[path] = "sha256:" + digest
74
+ observed = VerificationSourceSnapshot(
75
+ root=Path(str(target.get("sourceRoot", ""))), tracked_paths=frozenset(tracked),
76
+ generated_roots=sealed.generated_roots, input_paths=sealed.input_paths,
77
+ protected_files=protected, generated_files=generated, ignored_roots=sealed.ignored_roots,
78
+ )
79
+ if observed.root == sealed.root:
80
+ changes = compare_verification_sources(sealed, observed)
81
+ if changes.protected_changes:
82
+ limitations.append("Preserved protected source differs: " + ", ".join(changes.protected_changes[:20]))
83
+ if changes.unclassified_paths:
84
+ limitations.append("Preserved source has unclassified additions: " + ", ".join(changes.unclassified_paths[:20]))
85
+ if changes.tracked_paths_changed:
86
+ limitations.append("Preserved tracked source inventory differs from the verified generation")
87
+ return limitations
88
+
89
+
90
+ def read_run_evidence(
91
+ root: Path, owner: ComparisonOwner, target: Mapping[str, Any] | None = None, *,
92
+ budget: ReadBudget | None = None, fingerprints: dict[str, str | None] | None = None,
93
+ ) -> RunEvidence:
94
+ root = root.resolve()
95
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
96
+ fingerprints = {} if fingerprints is None else fingerprints
97
+ selection: RunEvidenceSelection = {"generation": None, "generationNumber": None, "attempts": [], "checks": []}
98
+ generation = source_root = None
99
+ limitations: list[str] = []
100
+ target_limitations: list[str] = []
101
+ rows: list[dict[str, Any]] = []
102
+ paths: set[str] = set()
103
+ entries = 0
104
+ changed: list[_ChangedInput] = []
105
+
106
+ def read_input(path: Path) -> bytes:
107
+ relative = project_artifact_relative_path(root, path)
108
+ if relative not in paths and len(paths) >= MAX_PATHS:
109
+ raise ComparisonError("Execution evidence artifact path limit reached")
110
+ paths.add(relative)
111
+ try:
112
+ body = _artifact_bytes(root, relative, fingerprints, budget)
113
+ except _ChangedInput as exc:
114
+ changed.append(exc)
115
+ raise
116
+ if body is None:
117
+ raise FileNotFoundError(f"Execution evidence input is missing: {relative}")
118
+ return body
119
+
120
+ def directory_entries(path: Path) -> Iterator[Path]:
121
+ nonlocal entries
122
+ directory = safe_qa_path(root, project_artifact_relative_path(root, path))
123
+ with os.scandir(directory) as scan:
124
+ for entry in scan:
125
+ entries += 1
126
+ if entries > MAX_PATHS:
127
+ raise ComparisonError("Execution evidence directory entry limit reached")
128
+ yield directory / entry.name
129
+
130
+ try:
131
+ if owner.get("kind") != "run":
132
+ raise ComparisonError("Runner evidence requires an implementation run owner")
133
+ settled = read_settled_implementation_generation(root, root / owner["path"], reader=read_input, directory_entries=directory_entries)
134
+ if changed:
135
+ raise changed[0]
136
+ _merge_fingerprints(fingerprints, settled.fingerprints)
137
+ selection["attempts"] = [[invocation, attempt] for invocation, attempt in settled.attempts]
138
+ limitations.extend(settled.limitations)
139
+ if settled.reference is None or settled.record is None:
140
+ return RunEvidence(None, None, (), selection, tuple(limitations))
141
+ record = settled.record
142
+ generation, source_root = _bare_digest(settled.reference.digest), record["sourceRoot"]
143
+ selection.update(generation=settled.reference.to_payload(), generationNumber=record["generation"])
144
+ target_limitations = _target_limitations(target, record, generation)
145
+ limitations.extend(target_limitations)
146
+ snapshot = collect_report_evidence_snapshot(root, root / owner["path"], reader=read_input, directory_entries=directory_entries,
147
+ generation_number=record["generation"], generation_reference=settled.reference)
148
+ _merge_fingerprints(fingerprints, snapshot.fingerprints)
149
+ selection["checks"] = [{"roleExecutionRef": item.role_execution_ref, "invocationRef": item.invocation_ref,
150
+ "attempt": item.attempt, "checkRuns": [[name, number] for name, number in item.check_runs]} for item in snapshot.selections]
151
+ for path, check in islice(snapshot.checks.items(), MAX_RECORDS):
152
+ receipt = check.record
153
+ if check.defect is not None or receipt is None or check.output is None:
154
+ limitations.append(f"Execution record is unavailable: {path}: {check.defect}")
155
+ continue
156
+ binding = list(target_limitations)
157
+ expected = {"runManifestPath": owner["path"], "generation": record["generation"],
158
+ "verificationGeneration": settled.reference.to_payload(), "worktree": record["sourceRoot"], "expectedHead": record["head"],
159
+ "verificationInputsPath": record["verificationInputsPath"], "verificationInputsDigest": record["verificationInputsDigest"]}
160
+ binding.extend(f"Execution record {key} differs from the settled generation" for key, value in expected.items() if receipt[key] != value)
161
+ identifier = "execution:" + path
162
+ rows.append({"id": "runner:" + digest_bytes(path.encode()), "recordId": identifier, "kind": "record", "origin": "runner-observed",
163
+ "support": "partial", "targetBound": not binding, "label": receipt["checkRef"], "command": receipt["command"],
164
+ "exitCode": receipt["exitCode"], "summary": output_tail(check.output), "outputTail": output_tail(check.output),
165
+ "recordedAt": receipt["finishedAt"] or "", "recordPath": path, "recordDigest": "sha256:" + fingerprints[path],
166
+ "verificationGeneration": settled.reference.to_payload(), "limitations": binding})
167
+ limitations.extend(reason for reason in binding if reason not in limitations)
168
+ if len(snapshot.checks) > MAX_RECORDS:
169
+ limitations.append(f"Execution evidence omitted {len(snapshot.checks) - MAX_RECORDS} records at its display limit")
170
+ except _ChangedInput:
171
+ raise
172
+ except (OSError, ValueError, KeyError, TypeError, PageBudgetExhausted) as exc:
173
+ if changed:
174
+ raise changed[0]
175
+ limitations.append(f"Execution evidence is unavailable: {exc}")
176
+ return RunEvidence(generation, source_root, tuple(rows), selection, tuple(limitations), tuple(target_limitations))
177
+
178
+
179
+ def run_selection_unchanged(root: Path, owner: ComparisonOwner, expected: RunEvidenceSelection | None, *, budget: ReadBudget | None = None) -> bool:
180
+ if expected is None:
181
+ return True
182
+ try:
183
+ return read_run_evidence(root, owner, budget=budget).selection == expected
184
+ except (OSError, ValueError, PageBudgetExhausted):
185
+ return False
186
+
187
+
188
+ def check_live_run_target(root: Path, owner: ComparisonOwner, target: Mapping[str, Any] | None) -> tuple[str, ...]:
189
+ try:
190
+ current = read_run_evidence(root, owner, target)
191
+ if current.generation is None or current.source_root is None:
192
+ return ()
193
+ source = Path(current.source_root)
194
+ if not source.exists():
195
+ return ()
196
+ if current.target_limitations:
197
+ return ()
198
+ if source.resolve() != source:
199
+ return ("Implementation source root changed before automatic comparison publication",)
200
+ with tempfile.TemporaryDirectory(prefix="okstra-comparison-live-") as temporary:
201
+ observed = collect_source(root.resolve(), source, "", Path(temporary))
202
+ observed.update(sourceRoot=current.source_root, generation=current.generation)
203
+ checked = read_run_evidence(root, owner, observed)
204
+ if checked.generation != current.generation:
205
+ return ("Verification generation changed while checking the implementation source",)
206
+ return checked.target_limitations
207
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
208
+ return (f"Implementation source could not be checked before automatic publication: {exc}",)
@@ -0,0 +1,198 @@
1
+ """Connect optional run comparison facts to report writing and closeout."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ from pathlib import Path
6
+ import subprocess
7
+ from typing import Any, Mapping
8
+
9
+ from okstra_vendor.jinja2 import TemplateError
10
+
11
+ from ..i18n import I18nError
12
+ from ..json_boundary import PageBudgetExhausted, load_owned_object_snapshot, read_bounded_bytes
13
+ from ..paths import find_asset_root
14
+ from ..qa_procedures import project_artifact_relative_path, safe_qa_path
15
+ from .baseline import (
16
+ MAX_BASELINE_BYTES, MAX_LIMITATION_SUMMARY_CHARS, ComparisonOwner,
17
+ read_baseline_status,
18
+ )
19
+ from .inputs import run_comparison_scope, task_comparison_owner
20
+ from .model import MAX_COMPARISON_INPUT_BYTES
21
+ from .run_evidence import read_run_evidence
22
+ from .target import _current_target, capture_target
23
+
24
+
25
+ def _run_scope(
26
+ root: Path, manifest_path: Path, manifest: Mapping[str, Any],
27
+ ) -> tuple[ComparisonOwner, Path] | None:
28
+ if manifest.get("taskType") != "implementation" or "implementationComparison" not in manifest:
29
+ return None
30
+ if manifest["implementationComparison"] is None:
31
+ raise ValueError("Run comparison declaration is invalid")
32
+ owner, directory, _ = run_comparison_scope(root, manifest_path, manifest)
33
+ safe_qa_path(root, (directory / "notes.json").relative_to(root).as_posix())
34
+ return owner, directory
35
+
36
+
37
+ def _saved_scope(root: Path, manifest_path: Path) -> tuple[ComparisonOwner, Path] | None:
38
+ path = safe_qa_path(root, project_artifact_relative_path(root, manifest_path))
39
+ manifest = load_owned_object_snapshot(
40
+ path, artifact="comparison run manifest", max_bytes=MAX_BASELINE_BYTES,
41
+ ).value
42
+ return _run_scope(root, path, manifest)
43
+
44
+
45
+ def _unavailable(reason: str) -> dict[str, Any]:
46
+ return {
47
+ "schemaVersion": "1.0", "owner": None, "baselineRef": None,
48
+ "targetRef": None, "notesPath": None, "generation": None,
49
+ "recordIds": [], "evidence": [], "notesGuide": None,
50
+ "limitations": [reason[:MAX_LIMITATION_SUMMARY_CHARS]],
51
+ }
52
+
53
+
54
+ def _notes_guide() -> tuple[str | None, list[str]]:
55
+ relative = ("templates", "reports", "implementation-comparison-notes.md")
56
+ try:
57
+ assets = find_asset_root(relative, is_present=Path.is_file)
58
+ if assets is None:
59
+ raise ValueError("Packaged comparison notes guide is missing")
60
+ return read_bounded_bytes(
61
+ assets.joinpath(*relative), max_bytes=MAX_COMPARISON_INPUT_BYTES,
62
+ artifact="implementation comparison notes guide",
63
+ ).decode("utf-8"), []
64
+ except (OSError, ValueError) as exc:
65
+ return None, [f"Comparison notes guide was not supplied: {exc}"]
66
+
67
+
68
+ def _writer_comparison(
69
+ root: Path, directory: Path, owner: ComparisonOwner,
70
+ target: Mapping[str, Any], record: Mapping[str, Any] | None,
71
+ ) -> dict[str, Any]:
72
+ baseline = read_baseline_status(root, directory, owner)
73
+ evidence = read_run_evidence(root, owner, record)
74
+ guide, guide_limits = _notes_guide()
75
+ metadata = {
76
+ "schemaVersion": "1.0", "owner": owner,
77
+ "baselineRef": baseline["baselineRef"],
78
+ "targetRef": target["targetRef"] if target["generation"] == evidence.generation else None,
79
+ "notesPath": (directory / "notes.json").relative_to(root).as_posix(),
80
+ "generation": evidence.generation, "recordIds": [], "evidence": [], "limitations": [],
81
+ "notesGuide": guide,
82
+ }
83
+ omitted = "Additional comparison context was omitted at the byte limit"
84
+ remaining = MAX_COMPARISON_INPUT_BYTES - len(json.dumps(metadata, ensure_ascii=True).encode()) - len(json.dumps(omitted).encode()) - 2
85
+ if remaining < 0:
86
+ metadata["notesGuide"] = None
87
+ guide_limits.append("Comparison notes guide exceeds the available metadata byte limit")
88
+ remaining = MAX_COMPARISON_INPUT_BYTES - len(json.dumps(metadata, ensure_ascii=True).encode()) - len(json.dumps(omitted).encode()) - 2
89
+ limits = [*guide_limits, *baseline["limitations"], *target["limitations"], *evidence.limitations]
90
+ if target["generation"] != evidence.generation:
91
+ limits.append("The preserved target does not identify the current completed generation")
92
+ for limitation in limits:
93
+ summary = limitation[:MAX_LIMITATION_SUMMARY_CHARS]
94
+ cost = len(json.dumps(summary, ensure_ascii=True).encode()) + 2
95
+ if cost > remaining:
96
+ metadata["limitations"].append(omitted)
97
+ return metadata
98
+ metadata["limitations"].append(summary)
99
+ remaining -= cost
100
+ for row in evidence.rows:
101
+ cost = len(json.dumps(row, ensure_ascii=True).encode()) + len(json.dumps(row["recordId"], ensure_ascii=True).encode()) + 4
102
+ if cost > remaining:
103
+ metadata["limitations"].append(omitted)
104
+ break
105
+ metadata["evidence"].append(row)
106
+ metadata["recordIds"].append(row["recordId"])
107
+ remaining -= cost
108
+ return metadata
109
+
110
+
111
+ def prepare_run_comparison(project_root: Path, manifest_path: Path) -> dict[str, Any] | None:
112
+ root = Path(project_root).resolve()
113
+ try:
114
+ scope = _saved_scope(root, manifest_path)
115
+ if scope is None:
116
+ return None
117
+ owner, directory = scope
118
+ evidence = read_run_evidence(root, owner)
119
+ target, record, _ = _current_target(root, directory, owner)
120
+ if evidence.generation is not None and evidence.source_root is not None and target["generation"] != evidence.generation:
121
+ capture_target(root, Path(evidence.source_root), directory, owner, generation=evidence.generation)
122
+ target, record, _ = _current_target(root, directory, owner)
123
+ return _writer_comparison(root, directory, owner, target, record)
124
+ except (OSError, ValueError, PageBudgetExhausted, subprocess.SubprocessError) as exc:
125
+ return _unavailable(f"Run comparison preparation failed: {exc}")
126
+
127
+
128
+ def read_run_comparison(project_root: Path, manifest_path: Path) -> dict[str, Any] | None:
129
+ root = Path(project_root).resolve()
130
+ try:
131
+ scope = _saved_scope(root, manifest_path)
132
+ if scope is None:
133
+ return None
134
+ owner, directory = scope
135
+ target, record, _ = _current_target(root, directory, owner)
136
+ return _writer_comparison(root, directory, owner, target, record)
137
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
138
+ return _unavailable(f"Run comparison input could not be read: {exc}")
139
+
140
+
141
+ def run_comparison_notes_paths(
142
+ project_root: Path, manifest_path: Path, manifest: Mapping[str, Any], *, role: str,
143
+ ) -> tuple[Path, ...]:
144
+ if role != "report-writer":
145
+ return ()
146
+ root = Path(project_root).resolve()
147
+ try:
148
+ scope = _run_scope(root, manifest_path, manifest)
149
+ except (OSError, ValueError):
150
+ return ()
151
+ return (scope[1] / "notes.json",) if scope is not None else ()
152
+
153
+
154
+ def finalize_run_comparison(project_root: Path, manifest_path: Path) -> dict[str, Any] | None:
155
+ from .publication import publish_comparison, read_comparison_status, update_implementation_comparison_link
156
+ from .run_evidence import check_live_run_target
157
+
158
+ root = Path(project_root).resolve()
159
+ warnings = []
160
+ try:
161
+ scope = _saved_scope(root, manifest_path)
162
+ if scope is None:
163
+ return None
164
+ owner, directory = scope
165
+ target, record, _ = _current_target(root, directory, owner)
166
+ limitations = check_live_run_target(root, owner, record) if record is not None and target["targetRef"] is not None else ()
167
+ if limitations:
168
+ comparison = {**read_comparison_status(root, directory, owner), "status": "stale"}
169
+ return {
170
+ "comparison": comparison, "linkStatus": "not-updated",
171
+ "warnings": [{"stage": "target", "message": message} for message in limitations],
172
+ }
173
+ comparison = publish_comparison(root, directory, owner)
174
+ except (OSError, ValueError, PageBudgetExhausted, subprocess.SubprocessError, TemplateError) as exc:
175
+ warnings.append({"stage": "publication", "message": str(exc)})
176
+ return {"comparison": {"status": "failed"}, "linkStatus": "not-updated", "warnings": warnings}
177
+ link_status = "not-updated"
178
+ if comparison["status"] in {"published", "reused"}:
179
+ try:
180
+ update_implementation_comparison_link(root, directory, owner)
181
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
182
+ link_status = "failed"
183
+ warnings.append({"stage": "link", "message": str(exc)})
184
+ else:
185
+ link_status = "updated"
186
+ else:
187
+ warnings.extend({"stage": "publication", "message": message} for message in comparison.get("warnings", []))
188
+ return {"comparison": comparison, "linkStatus": link_status, "warnings": warnings}
189
+
190
+
191
+ def finalize_task_comparison(project_root: Path, task_root: Path, task_key: str) -> dict[str, Any]:
192
+ from .publication import publish_comparison
193
+
194
+ try:
195
+ owner = task_comparison_owner(project_root, task_root, task_key)
196
+ return publish_comparison(project_root, None, owner)
197
+ except (OSError, ValueError, KeyError, PageBudgetExhausted, subprocess.SubprocessError, TemplateError, RecursionError, I18nError) as exc:
198
+ return {"status": "failed", "htmlPath": None, "warnings": [f"Task comparison could not be generated: {exc}"]}