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,47 @@
1
+ """Shared input contract for preserved implementation comparisons."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any, Literal, NotRequired, TypedDict
5
+
6
+ from .baseline import MAX_BASELINE_BYTES, ComparisonOwner
7
+ from .source import MAX_TOTAL_READ_BYTES
8
+
9
+ MAX_COMPARISON_INPUT_BYTES = 1024 * 1024
10
+ MAX_COMPARISON_READ_BYTES = 2 * MAX_TOTAL_READ_BYTES + 4 * MAX_BASELINE_BYTES
11
+ MAX_RECORDS = 1000
12
+
13
+
14
+ class RunCheckSelection(TypedDict):
15
+ roleExecutionRef: str
16
+ invocationRef: str
17
+ attempt: int
18
+ checkRuns: list[list[str | int]]
19
+
20
+
21
+ class RunEvidenceSelection(TypedDict):
22
+ generation: dict[str, str] | None
23
+ generationNumber: int | None
24
+ attempts: list[list[str | int]]
25
+ checks: list[RunCheckSelection]
26
+
27
+
28
+ class TaskEvidenceSelection(TypedDict):
29
+ task: dict[str, Any]
30
+ stages: dict[str, RunEvidenceSelection | None]
31
+ integrated: dict[str, Any]
32
+
33
+
34
+ class ComparisonSource(TypedDict):
35
+ kind: Literal["run", "trace", "task"]
36
+ owner: ComparisonOwner
37
+ path: str
38
+ digest: str
39
+ language: str
40
+ title: str
41
+ status: str
42
+ requirements: list[str | dict[str, Any]]
43
+ evidence: list[dict[str, Any]]
44
+ summary: NotRequired[str]
45
+ limitations: NotRequired[list[str]]
46
+ useCases: NotRequired[list[str | dict[str, Any]]]
47
+ stages: NotRequired[list[str | int]]
@@ -0,0 +1,195 @@
1
+ """Declare and preserve implementation baselines before lead dispatch."""
2
+ from __future__ import annotations
3
+
4
+ from contextlib import ExitStack
5
+ import json
6
+ from pathlib import Path
7
+ import subprocess
8
+ import sys
9
+ from typing import Any, Literal
10
+
11
+ from ..json_boundary import JsonBoundaryError, load_owned_object
12
+ from ..qa_procedures import safe_qa_path
13
+ from ..render import render_run_manifest
14
+ from ..run_context import dir_flock
15
+ from . import comparison_directory
16
+
17
+
18
+ def _read_manifest(path: Path) -> dict[str, Any]:
19
+ try:
20
+ return load_owned_object(path, artifact="run manifest")
21
+ except (OSError, JsonBoundaryError):
22
+ return {}
23
+
24
+
25
+ def _comparison_scope(project: Path, owner: dict[str, str], source: Path) -> dict[str, Any]:
26
+ project = project.resolve()
27
+ directory = comparison_directory(project, owner)
28
+ return {
29
+ "comparisonDirectory": directory.relative_to(project).as_posix(),
30
+ "owner": owner, "sourceRoot": str(source),
31
+ "baseline": {
32
+ "status": "unavailable", "baselineRef": None,
33
+ "notesPath": (directory / "notes.json").relative_to(project).as_posix(),
34
+ "limitations": ["Initial baseline capture did not complete"],
35
+ },
36
+ }
37
+
38
+
39
+ def _valid_scope(value: object, expected: dict[str, Any]) -> bool:
40
+ if not isinstance(value, dict) or value.get("owner") != expected["owner"]:
41
+ return False
42
+ baseline = value.get("baseline")
43
+ return (
44
+ value.get("comparisonDirectory") == expected["comparisonDirectory"]
45
+ and isinstance(value.get("sourceRoot"), str)
46
+ and isinstance(baseline, dict)
47
+ and {"status", "baselineRef", "notesPath", "limitations"} <= baseline.keys()
48
+ and isinstance(baseline["limitations"], list)
49
+ and all(isinstance(item, str) for item in baseline["limitations"])
50
+ )
51
+
52
+
53
+ def _save_comparison(ctx: dict[str, Any], comparison: dict[str, Any]) -> None:
54
+ ctx["IMPLEMENTATION_COMPARISON_JSON"] = json.dumps(comparison, ensure_ascii=False)
55
+ render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
56
+
57
+
58
+ def declare_implementation_comparison(
59
+ ctx: dict[str, Any], task_source: Path, stage: int, *, new_run: bool,
60
+ ) -> None:
61
+ recorded = _read_manifest(Path(ctx["RUN_MANIFEST_PATH"]))
62
+ if not new_run and "implementationComparison" not in recorded:
63
+ ctx.pop("IMPLEMENTATION_COMPARISON_JSON", None)
64
+ return
65
+ project = Path(ctx["PROJECT_ROOT"])
66
+ initial = {
67
+ "schemaVersion": "1.0",
68
+ **_comparison_scope(project, {
69
+ "kind": "run", "path": ctx["RUN_MANIFEST_RELATIVE_PATH"],
70
+ "taskKey": ctx["TASK_KEY"], "runSeq": ctx["RUN_MANIFESTS_SEQ"], "stage": str(stage),
71
+ }, Path(ctx.get("EXECUTOR_WORKTREE_PATH") or project)),
72
+ "taskBaseline": {
73
+ **_comparison_scope(project, {
74
+ "kind": "task", "path": ctx["TASK_MANIFEST_RELATIVE_PATH"], "taskKey": ctx["TASK_KEY"],
75
+ }, task_source),
76
+ "captureState": "pending",
77
+ },
78
+ }
79
+ comparison = initial if new_run else recorded.get("implementationComparison")
80
+ if not new_run and not (
81
+ _valid_scope(comparison, initial)
82
+ and _valid_scope(comparison.get("taskBaseline"), initial["taskBaseline"])
83
+ ):
84
+ comparison = initial
85
+ comparison["taskBaseline"]["captureState"] = "attempted"
86
+ for scope in (comparison, comparison["taskBaseline"]):
87
+ scope["baseline"]["limitations"] = ["Recorded comparison metadata is invalid; baseline was not recollected"]
88
+ ctx["IMPLEMENTATION_COMPARISON_JSON"] = json.dumps(comparison, ensure_ascii=False)
89
+
90
+
91
+ def _baseline_result(
92
+ project: Path, scope: dict[str, Any], action: Literal["capture", "status"], baseline_ref: str = "",
93
+ ) -> dict[str, Any]:
94
+ from . import capture_baseline, read_baseline_status
95
+
96
+ directory = project / scope["comparisonDirectory"]
97
+ try:
98
+ if action == "capture":
99
+ return capture_baseline(project, Path(scope["sourceRoot"]), directory, scope["owner"], baseline_ref=baseline_ref)
100
+ return read_baseline_status(project, directory, scope["owner"])
101
+ except (OSError, ValueError, subprocess.SubprocessError) as exc:
102
+ return {
103
+ **scope["baseline"], "status": "unavailable", "baselineRef": None,
104
+ "limitations": [f"Baseline collection failed: {exc}"],
105
+ }
106
+
107
+
108
+ def _task_capture_blocker(ctx: dict[str, Any], scope: dict[str, Any]) -> dict[str, Any] | None:
109
+ manifest_path = Path(ctx["RUN_MANIFEST_PATH"])
110
+ for path in (Path(ctx["TASK_ROOT"]) / "runs/implementation").rglob("run-manifest-*.json"):
111
+ if path == manifest_path:
112
+ continue
113
+ recorded = _read_manifest(path)
114
+ comparison = recorded.get("implementationComparison")
115
+ prior = comparison.get("taskBaseline") if isinstance(comparison, dict) else None
116
+ resources = recorded.get("resources")
117
+ prompt = resources.get("leadExecutionPromptPath") if isinstance(resources, dict) else None
118
+ try:
119
+ unpublished = isinstance(prompt, str) and bool(prompt) and not safe_qa_path(Path(ctx["PROJECT_ROOT"]), prompt).exists()
120
+ except (OSError, ValueError):
121
+ unpublished = False
122
+ if (
123
+ isinstance(comparison, dict) and comparison.get("schemaVersion") == "1.0"
124
+ and _valid_scope(prior, scope)
125
+ and prior.get("sourceRoot") == scope["sourceRoot"]
126
+ and prior.get("captureState") == "pending"
127
+ and prior["baseline"]["baselineRef"] is None
128
+ and unpublished
129
+ ):
130
+ continue
131
+ if _valid_scope(prior, scope) and prior["baseline"]["baselineRef"] is None:
132
+ return prior["baseline"]
133
+ return {
134
+ **scope["baseline"],
135
+ "limitations": ["Task baseline was not captured before an earlier implementation run"],
136
+ }
137
+ return None
138
+
139
+
140
+ def _capture_task_baseline(
141
+ ctx: dict[str, Any], comparison: dict[str, Any], task_base: str, *, new_run: bool,
142
+ ) -> dict[str, Any]:
143
+ project = Path(ctx["PROJECT_ROOT"])
144
+ scope = comparison["taskBaseline"]
145
+ if not new_run:
146
+ return _baseline_result(project, scope, "status")
147
+ with ExitStack() as locks:
148
+ try:
149
+ locks.enter_context(dir_flock(Path(ctx["TASK_ROOT"]), ".implementation-comparison.lock"))
150
+ except OSError as exc:
151
+ scope["captureState"] = "attempted"
152
+ return {
153
+ **scope["baseline"], "status": "unavailable", "baselineRef": None,
154
+ "limitations": [f"Task baseline lock failed: {exc}"],
155
+ }
156
+ path = project / scope["comparisonDirectory"] / "baseline.json"
157
+ if path.exists() or path.is_symlink() or scope.get("captureState") != "pending":
158
+ return _baseline_result(project, scope, "status")
159
+ blocked = _task_capture_blocker(ctx, scope)
160
+ if blocked is not None:
161
+ return blocked
162
+ scope["captureState"] = "attempted"
163
+ _save_comparison(ctx, comparison)
164
+ scope["baseline"] = _baseline_result(project, scope, "capture", task_base)
165
+ _save_comparison(ctx, comparison)
166
+ return scope["baseline"]
167
+
168
+
169
+ def capture_implementation_comparison(
170
+ ctx: dict[str, Any], *, stage_base: str, task_base: str, new_run: bool,
171
+ ) -> None:
172
+ encoded = ctx.get("IMPLEMENTATION_COMPARISON_JSON")
173
+ if encoded is None:
174
+ return
175
+ comparison = json.loads(encoded)
176
+ previous_run = comparison["baseline"]
177
+ run_result = _baseline_result(Path(ctx["PROJECT_ROOT"]), comparison, "capture" if new_run else "status", stage_base)
178
+ comparison["baseline"] = (
179
+ previous_run if not new_run and run_result["baselineRef"] is None and previous_run["baselineRef"] is None
180
+ else run_result
181
+ )
182
+ previous_task = comparison["taskBaseline"]["baseline"]
183
+ task_result = _capture_task_baseline(ctx, comparison, task_base, new_run=new_run)
184
+ comparison["taskBaseline"]["baseline"] = (
185
+ previous_task if not new_run and task_result["baselineRef"] is None and previous_task["baselineRef"] is None
186
+ else task_result
187
+ )
188
+ for scope in (comparison, comparison["taskBaseline"]):
189
+ result = scope["baseline"]
190
+ if result["status"] != "complete":
191
+ print(
192
+ f"implementation-comparison: {scope['owner']['kind']} baseline {result['status']}: "
193
+ + "; ".join(result["limitations"]), file=sys.stderr,
194
+ )
195
+ _save_comparison(ctx, comparison)
@@ -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)