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,118 @@
1
+ """Reuse existing explanations only when their stored scope matches preserved bytes."""
2
+ from __future__ import annotations
3
+
4
+ import base64
5
+ import binascii
6
+ from pathlib import Path
7
+ import re
8
+ from typing import Any, Mapping
9
+
10
+ from ..business_flow.contracts import artifact_path, fingerprint, schema_definition
11
+ from ..final_report_schema import validate
12
+ from ..json_boundary import ReadBudget, parse_owned_snapshot
13
+ from .baseline import ComparisonError
14
+ from .inputs import _ChangedInput, _artifact_bytes
15
+ from .model import MAX_RECORDS
16
+ from .source import MAX_FILE_READ_BYTES, MAX_GIT_COMMAND_BYTES, digest_bytes
17
+
18
+
19
+ def _stored_body_matches(encoded: object, expected_digest: str, maximum: int) -> bool:
20
+ if not isinstance(encoded, str) or len(encoded) > 4 * ((maximum + 2) // 3):
21
+ return False
22
+ try:
23
+ body = base64.b64decode(encoded, validate=True)
24
+ except (ValueError, binascii.Error):
25
+ return False
26
+ return len(body) <= maximum and digest_bytes(body) == expected_digest
27
+
28
+
29
+ def _matching_snapshot(capture: Mapping[str, Any] | None, snapshot: Mapping[str, Any]) -> bool:
30
+ if not capture or capture.get("status") != "complete" or not capture.get("completeInventory") or snapshot.get("gaps"):
31
+ return False
32
+ if capture.get("sourceRoot") != snapshot.get("root") or capture.get("head") != snapshot.get("head"):
33
+ return False
34
+ rows = capture.get("files", [])
35
+ if any(row.get("status") != "complete" for row in rows):
36
+ return False
37
+ files = {row["path"]: row.get("digest") for row in rows}
38
+ index = capture.get("git", {}).get("index-before", {})
39
+ digest = index.get("stdout", {}).get("storedDigest")
40
+ if not index.get("complete") or index.get("returncode") != 0 or not digest:
41
+ return False
42
+ if (files != snapshot.get("files") or digest != snapshot.get("indexDigest")
43
+ or snapshot.get("digest") != fingerprint({"head": capture["head"], "files": files, "index": digest})):
44
+ return False
45
+ dirty = snapshot.get("dirty")
46
+ if not isinstance(dirty, Mapping) or any(path not in files for path in dirty):
47
+ return False
48
+ return (_stored_body_matches(snapshot.get("indexPatch"), digest, MAX_GIT_COMMAND_BYTES)
49
+ and all(_stored_body_matches(body, files[path], MAX_FILE_READ_BYTES) for path, body in dirty.items()))
50
+
51
+
52
+ def read_matching_business_explanations(
53
+ root: Path, source: Mapping[str, Any], captures: Mapping[str, tuple[Path, dict[str, Any] | None]], *,
54
+ budget: ReadBudget, fingerprints: dict[str, str | None],
55
+ ) -> tuple[list[dict[str, Any]], list[str]]:
56
+ rows: list[dict[str, Any]] = []
57
+ limitations: list[str] = []
58
+ sidecar = source["path"] + ".business-flow.json"
59
+ try:
60
+ raw = _artifact_bytes(root, sidecar, fingerprints, budget)
61
+ if raw is None:
62
+ return rows, limitations
63
+ links = parse_owned_snapshot(root / sidecar, raw, artifact="business flow taskLink").value
64
+ executions = links.get("executions")
65
+ if not isinstance(executions, list) or len(executions) > MAX_RECORDS:
66
+ raise ComparisonError("Existing business explanation list exceeds its limit or is invalid")
67
+ if validate(links, schema_definition("taskLink")) or links.get("taskKey") != source["owner"].get("taskKey"):
68
+ raise ComparisonError("Existing business explanation links do not match this task")
69
+ seen: set[str] = set()
70
+ for link in executions:
71
+ identifier = link["id"]
72
+ if not identifier or len(identifier) > 128 or re.fullmatch(r"[a-z0-9-]+", identifier) is None:
73
+ limitations.append("Existing business explanation has no valid stored execution identity")
74
+ continue
75
+ if identifier in seen:
76
+ limitations.append("A duplicate existing business explanation reference was ignored")
77
+ continue
78
+ seen.add(identifier)
79
+ path = artifact_path(root, "executions", identifier, "execution.json")
80
+ relative = path.relative_to(root).as_posix()
81
+ body = _artifact_bytes(root, relative, fingerprints, budget)
82
+ if body is None:
83
+ limitations.append("Existing business explanation execution is missing")
84
+ continue
85
+ execution = parse_owned_snapshot(path, body, artifact="business flow execution").value
86
+ projects = execution.get("projects")
87
+ if not isinstance(projects, list) or len(projects) != 1 or validate(execution, schema_definition("execution")):
88
+ limitations.append("Existing business explanation has a different project scope or invalid record")
89
+ continue
90
+ artifact_digests = execution.get("sourceArtifactDigests")
91
+ artifact_digest = artifact_digests.get(str((root / source["path"]).resolve())) if isinstance(artifact_digests, Mapping) else None
92
+ if (execution.get("id") != identifier or execution.get("status") not in {"complete", "partial"}
93
+ or artifact_digest != source["digest"] or execution["request"].get("task_key") != source["owner"].get("taskKey")):
94
+ limitations.append("Existing business explanation is not bound to this report original")
95
+ continue
96
+ matches = [side for side, (_, capture) in captures.items() if _matching_snapshot(capture, projects[0])]
97
+ if not matches:
98
+ limitations.append("Existing business explanation source scope or content digest does not match preserved comparison bytes")
99
+ continue
100
+ result = execution.get("result", {})
101
+ summary = result.get("summary")
102
+ if not isinstance(summary, str) or not summary or len(summary.encode()) > 64 * 1024:
103
+ limitations.append("Existing business explanation summary is missing or exceeds its byte limit")
104
+ continue
105
+ for side in matches:
106
+ if len(rows) >= MAX_RECORDS:
107
+ limitations.append("Additional existing business explanations were omitted at the evidence row limit")
108
+ return rows, limitations
109
+ identity = f"business:{identifier}:{side}"
110
+ rows.append({"id": identity, "recordId": identity, "kind": "document", "origin": "existing-document",
111
+ "support": "partial", "targetBound": False, "side": side, "label": result.get("title", identifier),
112
+ "summary": summary, "recordPath": relative, "recordDigest": digest_bytes(body),
113
+ "limitations": ["Reused stored explanation with matching source scope; its narrative and execution claims were not independently reverified"]})
114
+ except _ChangedInput:
115
+ raise
116
+ except (OSError, ValueError, KeyError, TypeError) as exc:
117
+ limitations.append(f"Existing business explanation was not reused: {exc}")
118
+ return rows, list(dict.fromkeys(limitations))
@@ -0,0 +1,113 @@
1
+ """Read recorded commit content without reconstructing a working-tree baseline."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ import os
6
+ from pathlib import Path, PurePosixPath
7
+ import re
8
+ from typing import Any
9
+
10
+ from .source import EXCLUDED_PARTS, MAX_FILE_READ_BYTES, MAX_PATHS, GitCollector, digest_bytes
11
+
12
+ _COMMIT_ID = re.compile(r"(?:[a-f0-9]{40}|[a-f0-9]{64})\Z")
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class RecordedCommitSource:
17
+ record: dict[str, Any]
18
+ contents: dict[str, bytes]
19
+
20
+
21
+ def read_recorded_commit_source(root: Path, commit: str, *, git: GitCollector) -> RecordedCommitSource:
22
+ record: dict[str, Any] = {
23
+ "head": None, "baselineCommit": commit, "files": [], "completeInventory": False,
24
+ "status": "unavailable", "reconstruction": "recorded-commit", "dirtyState": "unknown",
25
+ "limitations": ["Reconstructed commit content; original uncommitted state is unknown"],
26
+ "excludedParts": sorted(EXCLUDED_PARTS),
27
+ "scope": {"workingTreeText": "unavailable", "index": "unavailable",
28
+ "commitTree": "full-within-read-limits"},
29
+ }
30
+ contents: dict[str, bytes] = {}
31
+ if not isinstance(commit, str) or not _COMMIT_ID.fullmatch(commit):
32
+ record["limitations"].append("Original recorded commit identity is unavailable")
33
+ return RecordedCommitSource(record, contents)
34
+ resolved = git.run(root, f"recorded-{commit}", "--no-replace-objects", "rev-parse", "--verify", "--end-of-options", f"{commit}^{{commit}}")
35
+ if not resolved.complete or resolved.returncode != 0 or resolved.stdout.strip() != commit.encode():
36
+ record["limitations"].append("Original recorded commit cannot be read")
37
+ return RecordedCommitSource(record, contents)
38
+ record["head"] = commit
39
+ prefix_result = git.run(root, f"prefix-{commit}", "--no-replace-objects", "rev-parse", "--show-prefix")
40
+ if not prefix_result.complete or prefix_result.returncode != 0:
41
+ record["limitations"].append("Original recorded project scope cannot be resolved")
42
+ return RecordedCommitSource(record, contents)
43
+ prefix = os.fsdecode(prefix_result.stdout.removesuffix(b"\n"))
44
+ prefix_path = PurePosixPath(prefix)
45
+ if prefix and (prefix_path.is_absolute() or any(part in {".", ".."} for part in prefix_path.parts)
46
+ or prefix_path.as_posix() + "/" != prefix):
47
+ record["limitations"].append("Original recorded project scope is not a relative directory")
48
+ return RecordedCommitSource(record, contents)
49
+ tree = f"{commit}:{prefix}" if prefix else commit
50
+ listing = git.run(root, f"tree-{commit}", "--no-replace-objects", "ls-tree", "-r", "-l", "-z", "--full-tree", tree)
51
+ if not listing.complete or listing.returncode != 0:
52
+ record["limitations"].append(f"Recorded commit inventory is incomplete: {listing.reason or 'Git tree read failed'}")
53
+ return RecordedCommitSource(record, contents)
54
+ record["completeInventory"] = True
55
+ for raw in listing.stdout.split(b"\0"):
56
+ if not raw:
57
+ continue
58
+ metadata, separator, name = raw.partition(b"\t")
59
+ fields = metadata.split()
60
+ path = os.fsdecode(name)
61
+ parts = PurePosixPath(path).parts
62
+ if not separator or len(fields) != 4 or not parts or PurePosixPath(path).is_absolute() or any(p in {".", ".."} for p in parts):
63
+ record["completeInventory"] = False
64
+ record["limitations"].append("Recorded commit contains an invalid tree entry")
65
+ break
66
+ if any(part in EXCLUDED_PARTS for part in parts):
67
+ continue
68
+ if len(record["files"]) >= MAX_PATHS:
69
+ record["completeInventory"] = False
70
+ record["limitations"].append("Recorded commit source path limit reached")
71
+ break
72
+ mode, kind, object_id, raw_size = fields
73
+ row: dict[str, Any] = {
74
+ "path": path, "tracked": True, "mode": int(mode, 8), "digest": None,
75
+ "contentPath": None, "status": "partial", "object": object_id.decode("ascii"),
76
+ }
77
+ record["files"].append(row)
78
+ if kind != b"blob" or mode not in {b"100644", b"100755"}:
79
+ row.update({"kind": "symlink" if mode == b"120000" else "submodule",
80
+ "reason": "Recorded source is not a regular file; it was not followed"})
81
+ continue
82
+ row["size"] = int(raw_size)
83
+ if row["size"] > MAX_FILE_READ_BYTES:
84
+ row["reason"] = "Recorded source exceeds the file read budget"
85
+ continue
86
+ content = git.run(root, f"blob-{object_id.decode('ascii')}", "--no-replace-objects", "cat-file", "blob", object_id.decode("ascii"))
87
+ if not content.complete or content.returncode != 0 or len(content.stdout) != row["size"]:
88
+ row["reason"] = f"Recorded source content is incomplete: {content.reason or 'Git blob read failed'}"
89
+ continue
90
+ body = content.stdout
91
+ row.update({"digest": digest_bytes(body), "status": "complete"})
92
+ try:
93
+ is_text = "\0" not in body.decode("utf-8")
94
+ except UnicodeDecodeError:
95
+ is_text = False
96
+ row["kind"] = "text" if is_text else "binary"
97
+ if is_text:
98
+ contents[path] = body
99
+ for row in record["files"]:
100
+ if row.get("reason"):
101
+ record["limitations"].append(f"{row['path']}: {row['reason']}")
102
+ record.update({"status": "partial", "bytesPreserved": sum(map(len, contents.values())),
103
+ "gitBytesRead": git.budget.bytes_read})
104
+ return RecordedCommitSource(record, contents)
105
+
106
+
107
+ def recorded_commit_is_ancestor(root: Path, ancestor: str, descendant: str, *, git: GitCollector) -> bool | None:
108
+ if not all(isinstance(value, str) and _COMMIT_ID.fullmatch(value) for value in (ancestor, descendant)):
109
+ return None
110
+ result = git.run(root, f"ancestry-{ancestor}-{descendant}", "--no-replace-objects", "merge-base", "--is-ancestor", ancestor, descendant)
111
+ if not result.complete or result.returncode not in {0, 1}:
112
+ return None
113
+ return result.returncode == 0
@@ -0,0 +1,49 @@
1
+ """Render validated comparison data as a self-contained reader document."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any
5
+
6
+ from okstra_vendor.jinja2 import Environment, StrictUndefined, select_autoescape
7
+
8
+ from ..i18n import HTML_DICTIONARY_REL, load_dictionary
9
+ from ..paths import find_asset_root
10
+ from ..report_html.filters import paragraphs
11
+ from ..report_template_loader import report_template_loader
12
+ from .baseline import ComparisonError
13
+ from .source import digest_bytes
14
+
15
+
16
+ def render_comparison_html(data: dict[str, Any]) -> str:
17
+ """Read packaged assets and render data without publishing or reclassifying it.
18
+
19
+ Fixed labels use Korean for ``ko`` and English otherwise. Authored prose
20
+ retains the source language; the comparison assembler owns its evidence levels.
21
+ """
22
+ template = ("templates", "reports", "html", "implementation-comparison.template.html")
23
+ root = find_asset_root(template)
24
+ if root is None:
25
+ raise ComparisonError("Comparison HTML templates are unavailable")
26
+ templates = root / "templates" / "reports"
27
+ language = "ko" if data["source"]["language"] == "ko" else "en"
28
+ dictionary = load_dictionary(language, HTML_DICTIONARY_REL)
29
+ environment = Environment(
30
+ loader=report_template_loader(templates),
31
+ autoescape=select_autoescape(("html",)),
32
+ undefined=StrictUndefined,
33
+ )
34
+ environment.filters["paragraphs"] = paragraphs
35
+ changes = data["changes"]
36
+ assets = templates / "html" / "assets"
37
+ return environment.get_template("html/implementation-comparison.template.html").render(
38
+ data=data, language=language, labels=dictionary["comparison"],
39
+ affected=sorted({value for row in changes for value in row.get("affected", [])}),
40
+ stages=sorted({str(value) for row in changes for value in row.get("stages", [])}
41
+ | {str(row["stage"]) for row in data.get("stageCards", [])}),
42
+ changes_by_id={row["id"]: row for row in changes},
43
+ change_anchors={row["id"]: "change-" + digest_bytes(row["id"].encode()) for row in changes},
44
+ evidence_anchors={row["id"]: "evidence-" + digest_bytes(row["id"].encode()) for row in data["evidence"]},
45
+ evidence_by_id={row["id"]: row for row in data["evidence"]},
46
+ css=(assets / "base.css").read_text(encoding="utf-8")
47
+ + "\n" + (assets / "implementation-comparison.css").read_text(encoding="utf-8"),
48
+ js=(assets / "implementation-comparison.js").read_text(encoding="utf-8"),
49
+ )
@@ -0,0 +1,348 @@
1
+ """Resolve stored run originals without collecting implementation state."""
2
+ from __future__ import annotations
3
+
4
+ from collections.abc import Mapping
5
+ import json
6
+ import re
7
+ from pathlib import Path, PurePosixPath
8
+ from typing import Any
9
+
10
+ from ..final_report_schema import load_schema_for_data
11
+ from ..json_boundary import ReadBudget, load_owned_object_snapshot, parse_owned_snapshot
12
+ from ..paths import RunRef, task_manifest_file
13
+ from ..qa_procedures import safe_qa_path
14
+ from ..report_validation_identity import _report_run_seq
15
+ from ..trace_tasks import parse_trace_source
16
+ from .baseline import MAX_BASELINE_BYTES, ComparisonError, ComparisonOwner, _owner_and_directory
17
+ from .model import ComparisonSource, MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES, MAX_RECORDS
18
+ from .source import SOURCE_CHANGED_DURING_READ, digest_bytes, read_source_bytes
19
+
20
+ MAX_NORMALIZED_SUMMARY_CHARS = 64 * 1024
21
+ NORMALIZATION_DIAGNOSTIC_RESERVE_BYTES = 8192
22
+
23
+
24
+ class _ChangedInput(ComparisonError):
25
+ pass
26
+
27
+
28
+ def _artifact_bytes(root: Path, relative: str, fingerprints: dict[str, str | None], budget: ReadBudget, *, limit: int = MAX_BASELINE_BYTES) -> bytes | None:
29
+ if not isinstance(relative, str):
30
+ raise ComparisonError("Comparison input path must be a string")
31
+ path = PurePosixPath(relative)
32
+ if relative != path.as_posix() or path.is_absolute() or ".." in path.parts or not path.parts or path.parts[0] != ".okstra":
33
+ raise ComparisonError("Comparison input path must remain under .okstra")
34
+ try:
35
+ body, _, problem = read_source_bytes(root, relative, budget, file_limit=limit, shared_budget=budget)
36
+ except FileNotFoundError:
37
+ if fingerprints.get(relative) is not None:
38
+ raise _ChangedInput("Comparison input disappeared during assembly")
39
+ fingerprints[relative] = None
40
+ return None
41
+ if problem == SOURCE_CHANGED_DURING_READ:
42
+ raise _ChangedInput(f"Comparison input changed during assembly: {relative}")
43
+ if problem or body is None:
44
+ raise ComparisonError(f"Comparison input could not be read: {relative}: {problem}")
45
+ digest = digest_bytes(body)
46
+ if relative in fingerprints and fingerprints[relative] != digest:
47
+ raise _ChangedInput("Comparison input changed during assembly")
48
+ fingerprints[relative] = digest
49
+ return body
50
+
51
+
52
+ def _validate_source(root: Path, owner: dict[str, Any], source: Mapping[str, Any], fingerprints: dict[str, str | None], budget: ReadBudget) -> bool:
53
+ if len(json.dumps(source, ensure_ascii=True, separators=(",", ":")).encode()) > MAX_COMPARISON_INPUT_BYTES:
54
+ raise ComparisonError("Normalized comparison source exceeds its byte limit")
55
+ allowed = set(ComparisonSource.__required_keys__) | set(ComparisonSource.__optional_keys__)
56
+ if set(source) - allowed:
57
+ raise ComparisonError("Normalized comparison source has unsupported fields")
58
+ if source.get("owner") != owner or source.get("kind") != owner["kind"] or owner["kind"] not in {"trace", "run", "task"}:
59
+ raise ComparisonError("Comparison source owner is invalid")
60
+ for key in ("path", "digest", "language", "title", "status"):
61
+ if not isinstance(source.get(key), str):
62
+ raise ComparisonError(f"Comparison source requires {key}")
63
+ path = source["path"]
64
+ if owner["kind"] in {"trace", "task"}:
65
+ if path != owner["path"]:
66
+ raise ComparisonError("Comparison source does not belong to its owner")
67
+ elif not (root / path).is_relative_to((root / owner["path"]).parent.parent):
68
+ raise ComparisonError("Run report does not belong to its owner")
69
+ body = _artifact_bytes(root, path, fingerprints, budget)
70
+ if body is None or digest_bytes(body) != source["digest"]:
71
+ return False
72
+ if owner["kind"] == "trace":
73
+ trace = parse_trace_source(body)
74
+ if trace.frontmatter.get("createdAt") != owner.get("createdAt"):
75
+ raise ComparisonError("Trace creation identity does not match its owner")
76
+ elif owner["kind"] == "task":
77
+ manifest = parse_owned_snapshot(root / path, body, artifact="comparison task manifest").value
78
+ if task_manifest_file((root / path).parent) != root / path or manifest.get("taskKey") != owner.get("taskKey"):
79
+ raise ComparisonError("Comparison source does not identify its canonical task")
80
+ else:
81
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
82
+ manifest = parse_owned_snapshot(root / owner["path"], raw, artifact="comparison run manifest").value if raw is not None else {}
83
+ expected_owner, _, report_path = run_comparison_scope(root, root / owner["path"], manifest)
84
+ if expected_owner != owner:
85
+ raise ComparisonError("Run manifest identity does not match its owner")
86
+ if report_path.relative_to(root).as_posix() != path:
87
+ raise ComparisonError("Run report does not match the manifest's declared report")
88
+ for key in ("requirements", "useCases"):
89
+ values = source.get(key, [])
90
+ if not isinstance(values, list) or len(values) > MAX_RECORDS or any(not isinstance(value, (str, dict)) for value in values):
91
+ raise ComparisonError(f"Comparison source {key} is invalid")
92
+ if "summary" in source and not isinstance(source["summary"], str):
93
+ raise ComparisonError("Comparison source summary is invalid")
94
+ limitations = source.get("limitations", [])
95
+ if not isinstance(limitations, list) or len(limitations) > MAX_RECORDS or any(not isinstance(value, str) for value in limitations):
96
+ raise ComparisonError("Comparison source limitations are invalid")
97
+ records = source.get("evidence", [])
98
+ if not isinstance(records, list) or len(records) > MAX_RECORDS or any(not isinstance(row, dict) for row in records):
99
+ raise ComparisonError("Comparison source evidence is invalid")
100
+ if not isinstance(source.get("stages", []), list) or any(not isinstance(stage, (str, int)) or isinstance(stage, bool) for stage in source.get("stages", [])):
101
+ raise ComparisonError("Comparison source stages are invalid")
102
+ return True
103
+
104
+
105
+ def _project_artifact(project_root: Path, value: str | Path) -> Path:
106
+ requested = Path(project_root).absolute()
107
+ root = requested.resolve(strict=True)
108
+ path = Path(value)
109
+ if path.is_absolute():
110
+ anchor = requested if path.is_relative_to(requested) else root
111
+ if not path.is_relative_to(anchor):
112
+ anchor = next((parent for parent in path.parents if parent.resolve() == root), root)
113
+ path = path.relative_to(anchor)
114
+ return safe_qa_path(root, path.as_posix())
115
+
116
+
117
+ def run_comparison_scope(
118
+ project_root: Path, manifest_path: Path, manifest: Mapping[str, Any],
119
+ ) -> tuple[ComparisonOwner, Path, Path]:
120
+ root = Path(project_root).resolve(strict=True)
121
+ path = _project_artifact(project_root, manifest_path)
122
+ if manifest.get("taskType") != "implementation":
123
+ raise ComparisonError("Comparison run must be an implementation run")
124
+ categories = manifest.get("runSequencesByCategory")
125
+ seq = categories.get("manifests") if isinstance(categories, Mapping) else _report_run_seq(path)
126
+ if not isinstance(seq, str) or not seq.isascii() or not seq.isdigit():
127
+ raise ComparisonError("Comparison run manifest has no valid manifest sequence")
128
+ ref = RunRef.from_run_dir(path.parent.parent, seq=int(seq))
129
+ if ref.task_type != "implementation" or ref.manifest != path:
130
+ raise ComparisonError("Comparison run manifest is not at its canonical run path")
131
+ owner: ComparisonOwner = {"kind": "run", "path": path.relative_to(root).as_posix(), "runSeq": seq}
132
+ if "taskKey" in manifest:
133
+ owner["taskKey"] = manifest["taskKey"]
134
+ if ref.stage is not None:
135
+ owner["stage"] = str(ref.stage)
136
+ declaration = manifest.get("implementationComparison")
137
+ directory = None
138
+ if declaration is not None:
139
+ if not isinstance(declaration, dict) or declaration.get("schemaVersion") != "1.0" or declaration.get("owner") != owner:
140
+ raise ComparisonError("Run comparison declaration does not match its run")
141
+ directory = declaration.get("comparisonDirectory")
142
+ if not isinstance(directory, str) or not directory:
143
+ raise ComparisonError("Run comparison declaration requires its directory")
144
+ directory = _project_artifact(project_root, directory)
145
+ _, directory, _ = _owner_and_directory(root, directory, owner)
146
+ original = manifest.get("expectedReportRecordPath") or manifest.get("expectedReportPath")
147
+ if not isinstance(original, str) or not original:
148
+ raise ComparisonError("Run manifest does not declare its report original")
149
+ report = _project_artifact(project_root, original)
150
+ if report.parent != ref.reports_dir:
151
+ raise ComparisonError("Run report does not belong to its run")
152
+ return owner, directory, report
153
+
154
+
155
+ def resolve_run_comparison(project_root: Path, manifest_path: Path) -> tuple[ComparisonOwner, Path]:
156
+ path = _project_artifact(project_root, manifest_path)
157
+ manifest = load_owned_object_snapshot(path, artifact="comparison run manifest", max_bytes=MAX_BASELINE_BYTES).value
158
+ owner, directory, _ = run_comparison_scope(project_root, path, manifest)
159
+ return owner, directory
160
+
161
+
162
+ def _bounded_source(source: ComparisonSource, limitations: list[str]) -> ComparisonSource:
163
+ for key, maximum in (("summary", MAX_NORMALIZED_SUMMARY_CHARS), ("title", 4096)):
164
+ value = source.get(key, "")
165
+ if not isinstance(value, str):
166
+ raise ComparisonError(f"Run comparison {key} must be text")
167
+ if len(value) > maximum:
168
+ source[key] = value[:maximum]
169
+ limitations.append(f"Recorded {key} was truncated for the normalized source")
170
+ rows = {key: source[key] for key in ("requirements", "useCases", "evidence")}
171
+ source.update(requirements=[], useCases=[], evidence=[], limitations=limitations)
172
+ if any(not isinstance(source[key], str) or len(source[key]) > 128 for key in ("language", "status")):
173
+ raise ComparisonError("Run comparison language and status must be bounded text")
174
+ remaining = MAX_COMPARISON_INPUT_BYTES - len(json.dumps(source, ensure_ascii=True, separators=(",", ":")).encode()) - NORMALIZATION_DIAGNOSTIC_RESERVE_BYTES
175
+ for key, values in rows.items():
176
+ if not isinstance(values, list):
177
+ raise ComparisonError(f"Run comparison {key} must be an array")
178
+ for index, value in enumerate(values):
179
+ size = len(json.dumps(value, ensure_ascii=True, separators=(",", ":")).encode()) + 1
180
+ if index >= MAX_RECORDS or size > remaining:
181
+ limitations.append(f"Recorded {key} omitted {len(values) - index} rows at the normalized input limit")
182
+ break
183
+ source[key].append(value)
184
+ remaining -= size
185
+ return source
186
+
187
+
188
+ def read_run_comparison_source(
189
+ project_root: Path, owner: ComparisonOwner, *, budget: ReadBudget | None = None,
190
+ fingerprints: dict[str, str | None] | None = None,
191
+ ) -> ComparisonSource:
192
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
193
+ fingerprints = {} if fingerprints is None else fingerprints
194
+ path = _project_artifact(project_root, owner["path"])
195
+ root = Path(project_root).resolve(strict=True)
196
+ manifest_raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
197
+ manifest = parse_owned_snapshot(path, manifest_raw, artifact="comparison run manifest").value if manifest_raw is not None else {}
198
+ actual, _, report = run_comparison_scope(project_root, path, manifest)
199
+ if owner != actual:
200
+ raise ComparisonError("Comparison source belongs to a different run")
201
+ raw = _artifact_bytes(root, report.relative_to(root).as_posix(), fingerprints, budget)
202
+ if raw is None:
203
+ raise ComparisonError("Run comparison report original is missing")
204
+ limitations = []
205
+ source: ComparisonSource = {
206
+ "kind": "run", "owner": actual, "path": report.relative_to(root).as_posix(),
207
+ "digest": digest_bytes(raw), "language": "en", "title": report.stem,
208
+ "status": "unknown", "requirements": [], "evidence": [], "useCases": [],
209
+ "stages": [actual["stage"]] if actual.get("stage") else [],
210
+ }
211
+ if "implementationComparison" not in manifest:
212
+ limitations.append("This historical run has no original comparison capture declaration")
213
+ if report.suffix == ".md":
214
+ source["summary"] = raw.decode("utf-8")
215
+ limitations.append("Historical Markdown is retained as recorded narrative; structured evidence was not inferred")
216
+ else:
217
+ data = json.loads(raw)
218
+ if not isinstance(data, dict):
219
+ raise ComparisonError("Run report original must be a JSON object")
220
+ try:
221
+ load_schema_for_data(data)
222
+ except ValueError as exc:
223
+ limitations.append(str(exc)[:1024])
224
+ header, meta = data.get("header", {}), data.get("meta", {})
225
+ frontmatter, human = data.get("frontmatter", {}), data.get("humanSummary", {})
226
+ if any(not isinstance(value, dict) for value in (header, meta, frontmatter, human)):
227
+ raise ComparisonError("Run report metadata must be JSON objects")
228
+ if header.get("taskType", "implementation") != "implementation" or (actual.get("taskKey") and header.get("taskKey", actual["taskKey"]) != actual["taskKey"]):
229
+ raise ComparisonError("Report original belongs to a different run task")
230
+ source["language"] = meta.get("reportLanguage", "en")
231
+ source["title"] = human.get("headline") or frontmatter.get("title") or report.stem
232
+ summary = data.get("summary", [])
233
+ source["summary"] = human.get("outcome") or ("\n".join(row["summary"] for row in summary if isinstance(row, dict) and isinstance(row.get("summary"), str)) if isinstance(summary, list) else str(summary))
234
+ implementation = data.get("implementation", {})
235
+ if not isinstance(implementation, dict):
236
+ raise ComparisonError("Run implementation record must be a JSON object")
237
+ source["status"] = frontmatter.get("status", "unknown")
238
+ source["requirements"] = implementation.get("requirementCoverage", [])
239
+ source["useCases"] = implementation.get("useCases", [])
240
+ validation = implementation.get("validationEvidence", [])
241
+ if not isinstance(validation, list):
242
+ raise ComparisonError("Run validation evidence must be a JSON array")
243
+ if len(validation) > MAX_RECORDS:
244
+ limitations.append(f"Recorded validation evidence omitted {len(validation) - MAX_RECORDS} rows before normalization")
245
+ source["evidence"] = [{"id": f"validation-{index}", **{key: row[key] for key in ("command", "exitCode") if key in row},
246
+ "summary": row.get("outputTail", "")}
247
+ for index, row in enumerate(validation[:MAX_RECORDS], 1) if isinstance(row, dict)]
248
+ return _bounded_source(source, limitations)
249
+
250
+
251
+ def task_comparison_owner(project_root: Path, task_root: Path, task_key: str | None = None) -> ComparisonOwner:
252
+ root = Path(project_root).resolve(strict=True)
253
+ path = _project_artifact(project_root, task_manifest_file(task_root))
254
+ owner: ComparisonOwner = {"kind": "task", "path": path.relative_to(root).as_posix()}
255
+ if task_key is not None:
256
+ owner["taskKey"] = task_key
257
+ return owner
258
+
259
+
260
+ def resolve_task_comparison(project_root: Path, manifest_path: Path) -> tuple[ComparisonOwner, Path]:
261
+ root = Path(project_root).resolve(strict=True)
262
+ run_owner, _ = resolve_run_comparison(root, manifest_path)
263
+ ref = RunRef.from_run_dir((root / run_owner["path"]).parent.parent, seq=int(run_owner["runSeq"]))
264
+ path = task_manifest_file(ref.task_root)
265
+ manifest = load_owned_object_snapshot(safe_qa_path(root, path.relative_to(root).as_posix()),
266
+ artifact="comparison task manifest", max_bytes=MAX_BASELINE_BYTES).value
267
+ key = manifest.get("taskKey")
268
+ if not isinstance(key, str) or not key or (run_owner.get("taskKey") and run_owner["taskKey"] != key):
269
+ raise ComparisonError("Selected implementation run does not identify its task")
270
+ owner = task_comparison_owner(root, ref.task_root, key)
271
+ _, directory, _ = _owner_and_directory(root, None, owner)
272
+ return owner, directory
273
+
274
+
275
+ def read_task_comparison_source(
276
+ project_root: Path, owner: ComparisonOwner, *, budget: ReadBudget | None = None,
277
+ fingerprints: dict[str, str | None] | None = None, plan_path: str | None = None,
278
+ ) -> ComparisonSource:
279
+ root = Path(project_root).resolve(strict=True)
280
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
281
+ fingerprints = {} if fingerprints is None else fingerprints
282
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
283
+ path = root / owner["path"]
284
+ manifest = parse_owned_snapshot(path, raw, artifact="comparison task manifest").value if raw is not None else {}
285
+ if owner.get("kind") != "task" or task_manifest_file(path.parent) != path or manifest.get("taskKey") != owner.get("taskKey"):
286
+ raise ComparisonError("Comparison source does not identify its canonical task")
287
+ outcomes = manifest.get("phaseOutcome", {})
288
+ outcome = outcomes.get("implementation", {}) if isinstance(outcomes, dict) else {}
289
+ language = manifest.get("reportLanguage", "en")
290
+ limitations = []
291
+ if plan_path is not None and "reportLanguage" not in manifest:
292
+ plan = safe_qa_path(root, plan_path)
293
+ if plan.parent != RunRef.from_task_root(path.parent, "implementation-planning").reports_dir:
294
+ raise ComparisonError("Task comparison plan belongs to another task")
295
+ plan_raw = _artifact_bytes(root, plan_path, fingerprints, budget)
296
+ try:
297
+ payload = parse_owned_snapshot(plan, plan_raw, artifact="comparison task plan").value if plan_raw is not None else {}
298
+ meta = payload.get("meta", {})
299
+ language = meta.get("reportLanguage", "en") if isinstance(meta, dict) else "en"
300
+ except ValueError as exc:
301
+ limitations.append(f"Task report language was not recovered from the invalid latest plan: {exc}")
302
+ source: ComparisonSource = {
303
+ "kind": "task", "owner": owner, "path": owner["path"], "digest": digest_bytes(raw),
304
+ "language": language, "title": str(manifest.get("title") or owner["taskKey"]),
305
+ "status": str(outcome.get("state", "unknown")) if isinstance(outcome, dict) else "unknown",
306
+ "requirements": [], "evidence": [], "useCases": [],
307
+ }
308
+ return _bounded_source(source, limitations)
309
+
310
+
311
+ def read_comparison_before_commit(
312
+ root: Path, owner: ComparisonOwner, *, budget: ReadBudget,
313
+ fingerprints: dict[str, str | None],
314
+ ) -> str | None:
315
+ raw = _artifact_bytes(root, owner["path"], fingerprints, budget)
316
+ if raw is None:
317
+ return None
318
+ if owner["kind"] == "trace":
319
+ trace = parse_trace_source(raw)
320
+ if trace.frontmatter.get("createdAt") != owner.get("createdAt"):
321
+ raise ComparisonError("Trace creation identity does not match its owner")
322
+ value = trace.frontmatter.get("baseCommit")
323
+ elif owner["kind"] == "run":
324
+ from ..verification_input_ref import VerificationInputReference
325
+ from ..verification_inputs import DESIGN_REVIEW_INPUT_SCHEMA_VERSION, read_verification_inputs
326
+
327
+ manifest = parse_owned_snapshot(root / owner["path"], raw, artifact="comparison run manifest").value
328
+ actual, _, _ = run_comparison_scope(root, root / owner["path"], manifest)
329
+ if actual != owner:
330
+ raise ComparisonError("Historical comparison run identity changed")
331
+ reference = VerificationInputReference.from_artifact_fields(manifest)
332
+ if reference is None:
333
+ return None
334
+ ref = RunRef.from_manifest(root / owner["path"], manifest)
335
+ if reference.relative_path != ref.verification_inputs.relative_to(root).as_posix():
336
+ raise ComparisonError("Historical verification inputs belong to another run")
337
+
338
+ def reader(path: Path) -> bytes:
339
+ body = _artifact_bytes(root, path.relative_to(root).as_posix(), fingerprints, budget)
340
+ if body is None:
341
+ raise FileNotFoundError(path)
342
+ return body
343
+
344
+ inputs = read_verification_inputs(safe_qa_path(root, reference.relative_path), reference.digest, reader=reader)
345
+ value = inputs.get("reviewBase") if inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION else None
346
+ else:
347
+ return None
348
+ return value if isinstance(value, str) and re.fullmatch(r"[0-9a-f]{40}(?:[0-9a-f]{24})?", value) else None