okstra 0.234.1 → 0.235.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 (108) 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/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  99. package/runtime/skills/okstra-run/SKILL.md +31 -0
  100. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  101. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  102. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  103. package/runtime/templates/reports/html/i18n/en.json +113 -0
  104. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  105. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  106. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  107. package/runtime/templates/trace/trace.template.md +2 -0
  108. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,317 @@
1
+ """Publish owner-scoped comparison revisions and preserve the previous current view."""
2
+ from __future__ import annotations
3
+
4
+ from datetime import datetime, timezone
5
+ import html
6
+ import json
7
+ import os
8
+ from pathlib import Path
9
+ import re
10
+ import tempfile
11
+ from typing import Any, Mapping, cast
12
+
13
+ from ..i18n import HTML_DICTIONARY_REL, load_dictionary
14
+ from ..json_boundary import PageBudgetExhausted, ReadBudget, load_owned_object_snapshot, read_bounded_bytes, serialize_owned_object, write_owned_object_atomic
15
+ from ..qa_procedures import safe_qa_path
16
+ from ..paths import RunRef
17
+ from ..report_html.render import HtmlSourceChanged, write_html_atomic
18
+ from ..report_validation_identity import _report_run_seq
19
+ from ..report_view_artifacts import html_view_path, manifest_category_sequence
20
+ from ..run_context import dir_flock
21
+ from .assembly import MAX_ASSEMBLY_BYTES, ComparisonSource, assemble_comparison, comparison_fingerprints
22
+ from .baseline import MAX_BASELINE_BYTES, ComparisonError, ComparisonOwner, _owner_and_directory
23
+ from .html import render_comparison_html
24
+ from .inputs import read_run_comparison_source, read_task_comparison_source, run_comparison_scope
25
+ from .source import digest_bytes, read_source_bytes
26
+ from .model import MAX_COMPARISON_READ_BYTES
27
+ from .run_evidence import run_selection_unchanged
28
+
29
+ PUBLICATION_LOCK = ".report-publication.lock"
30
+ MAX_CURRENT_BYTES = MAX_BASELINE_BYTES
31
+ MAX_HTML_BYTES = MAX_ASSEMBLY_BYTES
32
+ _CURRENT_FILE = "current.json"
33
+ _LINK_BEGIN = "<!-- okstra:implementation-comparison:begin -->"
34
+ _LINK_END = "<!-- okstra:implementation-comparison:end -->"
35
+ _DIGEST = re.compile(r"[a-f0-9]{64}\Z")
36
+
37
+
38
+ def _output_location(root: Path, directory: Path, owner: ComparisonOwner, sequence: Any) -> tuple[Path, str]:
39
+ if owner["kind"] != "run":
40
+ return directory, "report-"
41
+ if not isinstance(sequence, str) or not re.fullmatch(r"[0-9]+", sequence):
42
+ raise ComparisonError("Comparison report sequence must be decimal")
43
+ run = RunRef.from_run_dir((root / owner["path"]).parent.parent, seq=int(owner["runSeq"]))
44
+ return run.reports_dir, f"implementation-comparison-{sequence}-r"
45
+
46
+
47
+ def _layout(root: Path, directory: Path, owner: ComparisonOwner, source: Mapping[str, Any]) -> tuple[Path, str, str | None, dict[str, str]]:
48
+ if owner["kind"] != "run":
49
+ return directory, "report-", None, {}
50
+ snapshot = load_owned_object_snapshot(safe_qa_path(root, owner["path"]), artifact="comparison owner manifest", max_bytes=MAX_BASELINE_BYTES)
51
+ actual_owner, actual_directory, report = run_comparison_scope(root, root / owner["path"], snapshot.value)
52
+ if actual_owner != owner or actual_directory != directory or report != safe_qa_path(root, source["path"]):
53
+ raise ComparisonError("Comparison source does not match its owner's report record")
54
+ sequence = manifest_category_sequence(snapshot.value, "reports") if "runSequencesByCategory" in snapshot.value else _report_run_seq(report)
55
+ output, prefix = _output_location(root, directory, owner, sequence)
56
+ return output, prefix, sequence, {owner["path"]: digest_bytes(snapshot.raw_bytes)}
57
+
58
+
59
+ def _current_paths(root: Path, directory: Path, owner: ComparisonOwner, current: Mapping[str, Any]) -> tuple[Path, Path]:
60
+ output, prefix = _output_location(root, directory, owner, current.get("reportSequence"))
61
+ stem = f"{prefix}{current['revision']:03d}"
62
+ paths = output / f"{stem}.data.json", output / f"{stem}.html"
63
+ for label, path in zip(("data", "html"), paths):
64
+ if current.get(f"{label}Path") != path.relative_to(root).as_posix():
65
+ raise ComparisonError("Comparison current output does not belong to its owner")
66
+ safe_qa_path(root, path.relative_to(root).as_posix())
67
+ return paths
68
+
69
+
70
+ def _required_inputs(root: Path, directory: Path, owner: ComparisonOwner, source_path: str) -> set[str]:
71
+ names = ("baseline.json",) if owner["kind"] == "task" else ("baseline.json", "notes.json", "target-current.json")
72
+ return {source_path, *((directory / name).relative_to(root).as_posix() for name in names)}
73
+
74
+
75
+ def _read_current(root: Path, directory: Path, owner: ComparisonOwner) -> dict[str, Any] | None:
76
+ path = directory / _CURRENT_FILE
77
+ if not path.exists() and not path.is_symlink():
78
+ return None
79
+ if path.is_symlink():
80
+ raise ComparisonError("Comparison current pointer is a symbolic link")
81
+ row = load_owned_object_snapshot(path, artifact="comparison current pointer", max_bytes=MAX_CURRENT_BYTES).value
82
+ fields = {"schemaVersion", "owner", "revision", "reportStatus", "inputDigest", "dataPath", "dataDigest", "htmlPath", "htmlDigest", "sourcePath", "sourceDigest", "sourceLanguage", "fingerprints", "generatedAt", "reportSequence"}
83
+ if "verificationSelection" in row:
84
+ fields.add("verificationSelection")
85
+ if owner["kind"] != "run" or not isinstance(row["verificationSelection"], dict):
86
+ raise ComparisonError("Comparison current verification selection is invalid")
87
+ if "taskSelection" in row:
88
+ fields.add("taskSelection")
89
+ if owner["kind"] != "task" or not isinstance(row["taskSelection"], dict):
90
+ raise ComparisonError("Comparison current task selection is invalid")
91
+ if (set(row) != fields or row.get("schemaVersion") != "1.0" or row.get("owner") != owner
92
+ or type(row.get("revision")) is not int or row["revision"] < 1
93
+ or row.get("reportStatus") not in ("ready", "partial")):
94
+ raise ComparisonError("Comparison current pointer has an invalid owner or revision")
95
+ for key in ("inputDigest", "dataDigest", "htmlDigest", "sourceDigest"):
96
+ if not isinstance(row.get(key), str) or not _DIGEST.fullmatch(row[key]):
97
+ raise ComparisonError("Comparison current pointer digest is invalid")
98
+ inputs = row["fingerprints"]
99
+ if not isinstance(inputs, dict) or any(not isinstance(key, str) or (value is not None and (not isinstance(value, str) or not _DIGEST.fullmatch(value))) for key, value in inputs.items()):
100
+ raise ComparisonError("Comparison current input fingerprints are invalid")
101
+ if not isinstance(row["sourceLanguage"], str) or not isinstance(row["generatedAt"], str):
102
+ raise ComparisonError("Comparison current source metadata is invalid")
103
+ source_path = safe_qa_path(root, row["sourcePath"])
104
+ output, _ = _output_location(root, directory, owner, row["reportSequence"])
105
+ if (owner["kind"] in {"trace", "task"} and row["sourcePath"] != owner["path"]) or (owner["kind"] == "run" and source_path.parent != output):
106
+ raise ComparisonError("Comparison current source does not belong to its owner")
107
+ required = _required_inputs(root, directory, owner, row["sourcePath"])
108
+ if not required <= inputs.keys() or inputs[row["sourcePath"]] != row["sourceDigest"]:
109
+ raise ComparisonError("Comparison current pointer omits its input fingerprints")
110
+ _current_paths(root, directory, owner, row)
111
+ return row
112
+
113
+
114
+ def _inputs_unchanged(root: Path, fingerprints: Mapping[str, str | None]) -> bool:
115
+ try:
116
+ return comparison_fingerprints(root, fingerprints) == fingerprints
117
+ except (OSError, ValueError, PageBudgetExhausted):
118
+ return False
119
+
120
+
121
+ def _verified_current(root: Path, directory: Path, owner: ComparisonOwner, current: Mapping[str, Any]) -> bool:
122
+ data_path, html_path = _current_paths(root, directory, owner, current)
123
+ expected = {path.relative_to(root).as_posix(): current[f"{label}Digest"] for label, path in zip(("data", "html"), (data_path, html_path))}
124
+ return _verified_files(root, expected)
125
+
126
+
127
+ def _verified_files(root: Path, expected: Mapping[str, str]) -> bool:
128
+ budget = ReadBudget(MAX_ASSEMBLY_BYTES + MAX_HTML_BYTES)
129
+ try:
130
+ for relative, digest in expected.items():
131
+ maximum = MAX_HTML_BYTES if relative.endswith(".html") else MAX_ASSEMBLY_BYTES
132
+ body, _, problem = read_source_bytes(root, relative, budget, file_limit=maximum)
133
+ if problem or body is None or digest_bytes(body) != digest:
134
+ return False
135
+ return True
136
+ except (OSError, ValueError):
137
+ return False
138
+
139
+
140
+ def _next_revision(directory: Path, prefix: str, current: Mapping[str, Any] | None) -> int:
141
+ pattern = re.compile(re.escape(prefix) + r"(\d{3,})\.(?:data\.json|html)$")
142
+ maximum = current["revision"] if current else 0
143
+ if directory.is_dir():
144
+ for name in os.listdir(directory):
145
+ match = pattern.fullmatch(name)
146
+ if match:
147
+ maximum = max(maximum, int(match.group(1)))
148
+ return maximum + 1
149
+
150
+
151
+ def _input_digest(owner: ComparisonOwner, source: Mapping[str, Any], fingerprints: Mapping[str, str | None], selection: Mapping[str, Any] | None = None) -> str:
152
+ inputs = {"owner": owner, "source": source, "fingerprints": fingerprints}
153
+ if selection is not None:
154
+ inputs["taskSelection" if owner["kind"] == "task" else "verificationSelection"] = selection
155
+ return digest_bytes(json.dumps(inputs, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode())
156
+
157
+
158
+ def _selection_unchanged(root: Path, owner: ComparisonOwner, expected: Mapping[str, Any] | None) -> bool:
159
+ if owner["kind"] != "task":
160
+ return run_selection_unchanged(root, owner, expected)
161
+ if expected is None:
162
+ return False
163
+ from .task_selection import read_task_comparison_selection
164
+
165
+ try:
166
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES)
167
+ selected = read_task_comparison_selection(root, (root / owner["path"]).parent, budget=budget)
168
+ if selected.owner != owner or selected.selection != expected.get("task"):
169
+ return False
170
+ stages = expected.get("stages")
171
+ if not isinstance(stages, dict):
172
+ return False
173
+ for stage in selected.selected_stages:
174
+ if str(stage.stage) not in stages:
175
+ return False
176
+ run_owner, _, _ = run_comparison_scope(root, root / stage.run_manifest,
177
+ load_owned_object_snapshot(safe_qa_path(root, stage.run_manifest), artifact="task comparison selected manifest",
178
+ max_bytes=MAX_BASELINE_BYTES, budget=budget).value)
179
+ if not run_selection_unchanged(root, run_owner, stages[str(stage.stage)], budget=budget):
180
+ return False
181
+ return set(stages) == {str(stage.stage) for stage in selected.selected_stages}
182
+ except (OSError, ValueError, KeyError, TypeError, PageBudgetExhausted):
183
+ return False
184
+
185
+
186
+ def _result(current: Mapping[str, Any] | None, status: str) -> dict[str, Any]:
187
+ fields = ("reportStatus", "revision", "inputDigest", "dataPath", "htmlPath", "generatedAt")
188
+ return {"status": status, **{key: current[key] if current else None for key in fields},
189
+ "warnings": ["Comparison inputs changed or are unavailable; regenerate from the stored source"] if status == "stale" else []}
190
+
191
+
192
+ def publish_comparison(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner, source: Mapping[str, Any] | None = None) -> dict[str, Any]:
193
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
194
+ with dir_flock(directory, PUBLICATION_LOCK):
195
+ selected = None
196
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES)
197
+ if identity["kind"] == "task":
198
+ from .task_selection import read_task_comparison_selection
199
+
200
+ if source is not None:
201
+ raise ComparisonError("Task comparison source must be resolved from its manifest")
202
+ selected = read_task_comparison_selection(root, (root / identity["path"]).parent, budget=budget)
203
+ if selected.owner != identity:
204
+ raise ComparisonError("Task comparison selection belongs to another task")
205
+ source = read_task_comparison_source(root, identity, budget=budget, fingerprints=selected.fingerprints, plan_path=selected.plan_path)
206
+ if identity["kind"] == "run":
207
+ if source is not None:
208
+ raise ComparisonError("Run comparison source must be resolved from its manifest")
209
+ source = read_run_comparison_source(root, identity, budget=budget)
210
+ if source is None:
211
+ raise ComparisonError("Trace comparison requires its normalized stored source")
212
+ request = cast(ComparisonSource, json.loads(json.dumps(source, ensure_ascii=True)))
213
+ current = _read_current(root, directory, identity)
214
+ if selected is not None:
215
+ from .task_assembly import assemble_task_comparison
216
+
217
+ assembled = assemble_task_comparison(root, directory, identity, request, selection=selected, budget=budget)
218
+ else:
219
+ assembled = assemble_comparison(root, directory, identity, request, budget=budget)
220
+ if assembled.data["status"] == "stale":
221
+ return _result(current, "stale")
222
+ output, prefix, sequence, layout_inputs = _layout(root, directory, identity, request)
223
+ fingerprints = dict(assembled.fingerprints)
224
+ if not _required_inputs(root, directory, identity, request["path"]) <= fingerprints.keys():
225
+ raise ComparisonError("Comparison could not inspect all required owner inputs; the previous current report was preserved")
226
+ for path, digest in layout_inputs.items():
227
+ if path in fingerprints and fingerprints[path] != digest:
228
+ return _result(current, "stale")
229
+ fingerprints[path] = digest
230
+ input_digest = _input_digest(identity, request, fingerprints, assembled.selection)
231
+ if current and current["inputDigest"] == input_digest and _verified_current(root, directory, identity, current):
232
+ return _result(current, "reused" if _inputs_unchanged(root, fingerprints) and _selection_unchanged(root, identity, assembled.selection) else "stale")
233
+ revision = _next_revision(output, prefix, current)
234
+ stem = f"{prefix}{revision:03d}"
235
+ data_path, html_path = output / f"{stem}.data.json", output / f"{stem}.html"
236
+ safe_qa_path(root, data_path.relative_to(root).as_posix())
237
+ safe_qa_path(root, html_path.relative_to(root).as_posix())
238
+ data = {**assembled.data, "generatedAt": datetime.now(timezone.utc).isoformat(), "inputDigest": input_digest}
239
+ document = render_comparison_html(data)
240
+ if len(document.encode("utf-8")) > MAX_HTML_BYTES:
241
+ raise ComparisonError("Comparison HTML exceeds its byte limit")
242
+ output.mkdir(parents=True, exist_ok=True)
243
+ with tempfile.TemporaryDirectory(prefix=".comparison-report-", dir=output) as temporary:
244
+ staging = Path(temporary)
245
+ data_temp, html_temp = staging / data_path.name, staging / html_path.name
246
+ encoded = serialize_owned_object(data_temp, data, artifact="implementation comparison report").encode()
247
+ if len(encoded) > MAX_ASSEMBLY_BYTES:
248
+ raise ComparisonError("Comparison data exceeds its byte limit")
249
+ write_owned_object_atomic(data_temp, data, artifact="implementation comparison report")
250
+ try:
251
+ write_html_atomic(html_temp, document, source_path=safe_qa_path(root, request["path"]), source_digest=request["digest"], max_input_bytes=MAX_BASELINE_BYTES)
252
+ except HtmlSourceChanged:
253
+ return _result(current, "stale")
254
+ staged = {data_temp.relative_to(root).as_posix(): digest_bytes(encoded), html_temp.relative_to(root).as_posix(): digest_bytes(document.encode())}
255
+ if not _verified_files(root, staged):
256
+ raise ComparisonError("Staged comparison contents changed or are unavailable")
257
+ published = {"schemaVersion": "1.0", "owner": identity, "revision": revision, "reportStatus": data["status"], "inputDigest": input_digest,
258
+ "dataPath": data_path.relative_to(root).as_posix(), "dataDigest": digest_bytes(encoded),
259
+ "htmlPath": html_path.relative_to(root).as_posix(), "htmlDigest": digest_bytes(document.encode()),
260
+ "sourcePath": request["path"], "sourceDigest": request["digest"], "sourceLanguage": request["language"],
261
+ "fingerprints": fingerprints, "generatedAt": data["generatedAt"], "reportSequence": sequence}
262
+ if assembled.selection is not None:
263
+ published["taskSelection" if identity["kind"] == "task" else "verificationSelection"] = assembled.selection
264
+ pointer = directory / _CURRENT_FILE
265
+ if len(serialize_owned_object(pointer, published, artifact="comparison current pointer").encode()) > MAX_CURRENT_BYTES:
266
+ raise ComparisonError("Comparison current pointer exceeds its byte limit")
267
+ os.replace(data_temp, data_path)
268
+ os.replace(html_temp, html_path)
269
+ if not _inputs_unchanged(root, fingerprints) or not _selection_unchanged(root, identity, assembled.selection):
270
+ return _result(current, "stale")
271
+ write_owned_object_atomic(pointer, published, artifact="comparison current pointer")
272
+ return _result(published, "published")
273
+
274
+
275
+ def read_comparison_status(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> dict[str, Any]:
276
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
277
+ current = _read_current(root, directory, identity)
278
+ if current is None:
279
+ return _result(None, "not-generated")
280
+ valid = (_verified_current(root, directory, identity, current) and _inputs_unchanged(root, current["fingerprints"])
281
+ and _selection_unchanged(root, identity, current.get("taskSelection" if identity["kind"] == "task" else "verificationSelection")))
282
+ latest = _read_current(root, directory, identity)
283
+ return _result(current, "current" if valid and latest == current else "stale")
284
+
285
+
286
+ def update_implementation_comparison_link(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> Path:
287
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
288
+ if identity["kind"] != "run":
289
+ raise ComparisonError("Only an implementation run has a main report comparison link")
290
+ with dir_flock(directory, PUBLICATION_LOCK):
291
+ current = _read_current(root, directory, identity)
292
+ if (current is None or not _verified_current(root, directory, identity, current) or not _inputs_unchanged(root, current["fingerprints"])
293
+ or not run_selection_unchanged(root, identity, current.get("verificationSelection"))):
294
+ raise ComparisonError("No unchanged comparison report is current")
295
+ source_path = safe_qa_path(root, current["sourcePath"])
296
+ main_html = html_view_path(source_path)
297
+ safe_qa_path(root, main_html.relative_to(root).as_posix())
298
+ before = read_bounded_bytes(main_html, max_bytes=MAX_HTML_BYTES, artifact="existing report HTML")
299
+ document = before.decode("utf-8")
300
+ comparison_html = safe_qa_path(root, current["htmlPath"])
301
+ href = comparison_html.relative_to(main_html.parent).as_posix()
302
+ labels = load_dictionary("ko" if current["sourceLanguage"] == "ko" else "en", HTML_DICTIONARY_REL)["comparison"]
303
+ label = html.escape(labels["title"], quote=True)
304
+ state = html.escape(labels["reportStatuses"][current["reportStatus"]])
305
+ block = _LINK_BEGIN + f'<nav aria-label="{label}"><a href="{html.escape(href, quote=True)}">{label}</a> <span>{state}</span></nav>' + _LINK_END
306
+ if _LINK_BEGIN in document or _LINK_END in document:
307
+ pattern = re.compile(re.escape(_LINK_BEGIN) + r".*?" + re.escape(_LINK_END), re.DOTALL)
308
+ if len(pattern.findall(document)) != 1:
309
+ raise ComparisonError("Existing comparison link block is incomplete or repeated")
310
+ document = pattern.sub(lambda _: block, document)
311
+ elif "</main>" in document:
312
+ document = document.replace("</main>", block + "</main>", 1)
313
+ else:
314
+ raise ComparisonError("Existing implementation HTML has no main region")
315
+ if not run_selection_unchanged(root, identity, current.get("verificationSelection")):
316
+ raise ComparisonError("Implementation verification selection changed before updating its comparison link")
317
+ return write_html_atomic(main_html, document, source_path=source_path, source_digest=current["sourceDigest"], expected_html_digest=digest_bytes(before), max_input_bytes=MAX_BASELINE_BYTES)
@@ -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}",)