okstra 0.234.0 → 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.
- package/dist/cli-registry.mjs +7 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
- package/dist/commands/implementation-report/implementation-report.mjs +73 -0
- package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
- package/dist/commands/trace/comparison.d.mts +39 -0
- package/dist/commands/trace/comparison.mjs +138 -0
- package/dist/commands/trace/comparison.mjs.map +1 -0
- package/dist/commands/trace/document.d.mts +8 -0
- package/dist/commands/trace/document.mjs +37 -0
- package/dist/commands/trace/document.mjs.map +1 -0
- package/dist/commands/trace/line-counts.d.mts +15 -0
- package/dist/commands/trace/line-counts.mjs +107 -0
- package/dist/commands/trace/line-counts.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +2 -1
- package/dist/commands/trace/model.mjs +13 -1
- package/dist/commands/trace/model.mjs.map +1 -1
- package/dist/commands/trace/progression.mjs +12 -7
- package/dist/commands/trace/progression.mjs.map +1 -1
- package/dist/commands/trace/task-link.d.mts +3 -0
- package/dist/commands/trace/task-link.mjs.map +1 -1
- package/dist/commands/trace/trace.mjs +66 -46
- package/dist/commands/trace/trace.mjs.map +1 -1
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +11 -5
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/types.d.mts +1 -0
- package/docs/architecture/storage-model.md +50 -0
- package/docs/cli.md +31 -15
- package/docs/project-structure-overview.md +6 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-tests-review.json +6 -0
- package/runtime/prompts/duties/test-reviewer.json +32 -0
- package/runtime/prompts/lead/report-writer.md +13 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
- package/runtime/python/okstra_ctl/code_review_census.py +38 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
- package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
- package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
- package/runtime/python/okstra_ctl/code_review_target.py +16 -6
- package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
- package/runtime/python/okstra_ctl/consumers.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +6 -26
- package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
- package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
- package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
- package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
- package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
- package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
- package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
- package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
- package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
- package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
- package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
- package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
- package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
- package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
- package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
- package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
- package/runtime/python/okstra_ctl/json_boundary.py +28 -8
- package/runtime/python/okstra_ctl/paths.py +7 -4
- package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
- package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
- package/runtime/python/okstra_ctl/render.py +4 -0
- package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
- package/runtime/python/okstra_ctl/report_finalize.py +18 -4
- package/runtime/python/okstra_ctl/report_html/render.py +46 -7
- package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
- package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
- package/runtime/python/okstra_ctl/run.py +16 -0
- package/runtime/python/okstra_ctl/stage_done.py +11 -3
- package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
- package/runtime/python/okstra_ctl/stage_map.py +3 -3
- package/runtime/python/okstra_ctl/trace_review.py +1 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
- package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
- package/runtime/python/okstra_ctl/verification_generation.py +3 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
- package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
- package/runtime/skills/okstra-code-review/SKILL.md +1 -1
- package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
- package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +31 -0
- package/runtime/skills/okstra-tdd/SKILL.md +75 -11
- package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
- package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
- package/runtime/templates/reports/html/i18n/en.json +113 -0
- package/runtime/templates/reports/html/i18n/ko.json +113 -0
- package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
- package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
- package/runtime/templates/trace/trace.template.md +2 -0
- 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}",)
|