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.
Files changed (109) 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 +12 -7
  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 +66 -46
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
  97. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  99. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +31 -0
  101. package/runtime/skills/okstra-tdd/SKILL.md +75 -11
  102. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  103. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  104. package/runtime/templates/reports/html/i18n/en.json +113 -0
  105. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  106. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  107. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  108. package/runtime/templates/trace/trace.template.md +2 -0
  109. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,254 @@
1
+ """Owner-bound baseline publication and read-only resume."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import os
6
+ import tempfile
7
+ from collections.abc import Mapping
8
+ from datetime import datetime, timezone
9
+ from pathlib import Path, PurePosixPath
10
+ from typing import Any, Literal, TypedDict
11
+
12
+ from ..json_boundary import (
13
+ JsonBoundaryError, ReadBudget, load_owned_object_snapshot, write_owned_object_atomic,
14
+ )
15
+ from ..run_context import dir_flock
16
+ from .source import (
17
+ MAX_FILE_READ_BYTES, MAX_GIT_COMMAND_BYTES, MAX_GIT_TOTAL_BYTES, MAX_PATHS,
18
+ MAX_TOTAL_READ_BYTES, collect_source, digest_bytes, read_source_bytes,
19
+ )
20
+
21
+ MAX_BASELINE_BYTES = 16 * 1024 * 1024
22
+ MAX_OWNER_BYTES = 8192
23
+ MAX_BASELINE_RESPONSE_BYTES = 64 * 1024
24
+ MAX_LIMITATION_SUMMARY_CHARS = 1024
25
+ OWNER_FIELDS = frozenset({"kind", "path", "taskKey", "runSeq", "stage", "attempt", "createdAt"})
26
+
27
+
28
+ class ComparisonOwner(TypedDict, total=False):
29
+ kind: Literal["run", "trace", "task"]
30
+ path: str
31
+ taskKey: str
32
+ runSeq: str
33
+ stage: str
34
+ attempt: str
35
+ createdAt: str
36
+
37
+
38
+ class ComparisonError(ValueError):
39
+ """Comparison identity or artifact confinement does not match its owner."""
40
+
41
+
42
+ def comparison_directory(project_root: Path, owner: ComparisonOwner) -> Path:
43
+ root = Path(project_root).resolve(strict=True)
44
+ if not isinstance(owner, Mapping) or set(owner) - OWNER_FIELDS:
45
+ raise ComparisonError("Comparison owner has unsupported fields")
46
+ if len(json.dumps(dict(owner), ensure_ascii=True).encode()) > MAX_OWNER_BYTES:
47
+ raise ComparisonError("Comparison owner exceeds its byte limit")
48
+ if owner.get("kind") not in {"run", "trace", "task"} or not isinstance(owner.get("path"), str):
49
+ raise ComparisonError("Comparison owner requires kind and path")
50
+ for value in owner.values():
51
+ if not isinstance(value, str) or not value or len(value) > 4096 or "\0" in value:
52
+ raise ComparisonError("Comparison owner fields must be bounded nonempty strings")
53
+ relative = PurePosixPath(owner["path"])
54
+ if relative.is_absolute() or any(part in {"..", "."} for part in relative.parts) or not relative.parts or relative.parts[0] != ".okstra":
55
+ raise ComparisonError("Comparison owner path must be project-relative under .okstra")
56
+ owner_path = root / owner["path"]
57
+ return (
58
+ owner_path.parent / f"{owner_path.stem}.comparison" if owner["kind"] == "trace"
59
+ else owner_path.parent / "implementation-comparison" if owner["kind"] == "task"
60
+ else owner_path.parent.parent / "comparison" / owner_path.stem
61
+ )
62
+
63
+
64
+ def _owner_and_directory(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> tuple[Path, Path, dict[str, Any]]:
65
+ requested_root = Path(project_root).absolute()
66
+ root = requested_root.resolve(strict=True)
67
+ canonical = comparison_directory(root, owner)
68
+ owner_path = root / owner["path"]
69
+ expected = canonical.parent if owner["kind"] == "run" else canonical
70
+ if comparison_dir is None:
71
+ directory = canonical
72
+ else:
73
+ directory = Path(comparison_dir)
74
+ directory = directory if directory.is_absolute() else root / directory
75
+ if directory.is_relative_to(requested_root):
76
+ directory = root / directory.relative_to(requested_root)
77
+ actual = directory.resolve()
78
+ if not actual.is_relative_to(root) or not owner_path.resolve().is_relative_to(root):
79
+ raise ComparisonError("Comparison path escapes its project")
80
+ if owner["kind"] == "run":
81
+ allowed = actual.is_relative_to(expected.resolve()) and actual != expected.resolve()
82
+ else:
83
+ allowed = actual == expected.resolve()
84
+ if not allowed:
85
+ raise ComparisonError("Comparison directory does not belong to its owner")
86
+ for path in (owner_path, directory):
87
+ current = root
88
+ for part in path.relative_to(root).parts:
89
+ current /= part
90
+ if current.is_symlink():
91
+ raise ComparisonError("Comparison paths must not follow symbolic links")
92
+ return root, actual, dict(owner)
93
+
94
+
95
+ def _seal(record: dict[str, Any]) -> dict[str, Any]:
96
+ record["recordDigest"] = digest_bytes(json.dumps(record, sort_keys=True, ensure_ascii=True).encode())
97
+ return record
98
+
99
+
100
+ def _response(root: Path, directory: Path, record: dict[str, Any] | None, digest: str | None, reason: str = "", *, record_name: str = "baseline.json") -> dict[str, Any]:
101
+ limitations = [reason] if reason else record.get("limitations", []) if record else []
102
+ response = {
103
+ "status": record["status"] if record else "unavailable",
104
+ "directory": directory.relative_to(root).as_posix(),
105
+ ("baselineRef" if record_name == "baseline.json" else "targetRef"): {
106
+ "path": (directory / record_name).relative_to(root).as_posix(), "digest": digest,
107
+ } if record else None,
108
+ "notesPath": (directory / "notes.json").relative_to(root).as_posix(),
109
+ "limitations": [], "limitationsTotal": len(limitations), "limitationsOmitted": False,
110
+ }
111
+ size = len(json.dumps(response, ensure_ascii=True).encode()) + 1
112
+ if size > MAX_BASELINE_RESPONSE_BYTES:
113
+ raise ComparisonError("Comparison response metadata exceeds its byte limit")
114
+ abbreviated = False
115
+ for limitation in limitations:
116
+ summary = limitation[:MAX_LIMITATION_SUMMARY_CHARS]
117
+ if summary != limitation:
118
+ summary += "..."
119
+ abbreviated = True
120
+ addition = len(json.dumps(summary, ensure_ascii=True).encode()) + (2 if response["limitations"] else 0)
121
+ if size + addition > MAX_BASELINE_RESPONSE_BYTES:
122
+ break
123
+ response["limitations"].append(summary)
124
+ size += addition
125
+ response["limitationsOmitted"] = abbreviated or len(response["limitations"]) < len(limitations)
126
+ return response
127
+
128
+
129
+ def capture_baseline(
130
+ project_root: Path, source_root: Path, comparison_dir: Path | None,
131
+ owner: ComparisonOwner, *, baseline_ref: str = "",
132
+ ) -> dict[str, Any]:
133
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
134
+ source = Path(source_root).resolve()
135
+ if not isinstance(baseline_ref, str) or len(baseline_ref) > 4096 or "\0" in baseline_ref:
136
+ raise ComparisonError("Baseline ref is invalid")
137
+ directory.mkdir(parents=True, exist_ok=True)
138
+ with dir_flock(directory, ".comparison.lock"):
139
+ return _capture_source_record(root, source, directory, identity, baseline_ref)
140
+
141
+
142
+ def _capture_source_record(
143
+ root: Path, source: Path, directory: Path, identity: dict[str, Any], requested_ref: str,
144
+ *, record_name: str = "baseline.json", metadata: dict[str, Any] | None = None,
145
+ ) -> dict[str, Any]:
146
+ label = record_name.removesuffix(".json")
147
+ path = directory / record_name
148
+ if path.exists() or path.is_symlink():
149
+ response, record = _read_capture(root, directory, identity, record_name=record_name)
150
+ if record and (record.get("sourceRoot") != str(source) or record.get("requestedRef") != requested_ref):
151
+ raise ComparisonError(f"{label.capitalize()} source or reference conflicts with its original capture")
152
+ return response
153
+ record: dict[str, Any] = {
154
+ "schemaVersion": "1.0", "owner": identity, "projectRoot": str(root),
155
+ "sourceRoot": str(source), "requestedRef": requested_ref,
156
+ "capturedAt": datetime.now(timezone.utc).isoformat(), "status": "unavailable",
157
+ "limitations": ["Initial capture did not complete; current source will not replace the baseline"],
158
+ "files": [], "git": {}, "state": "capture-started",
159
+ "limits": {"paths": MAX_PATHS, "fileReadBytes": MAX_FILE_READ_BYTES,
160
+ "totalReadBytes": MAX_TOTAL_READ_BYTES, "gitCommandBytes": MAX_GIT_COMMAND_BYTES,
161
+ "gitTotalBytes": MAX_GIT_TOTAL_BYTES},
162
+ }
163
+ record.update(metadata or {})
164
+ write_owned_object_atomic(path, _seal(dict(record)), artifact=f"implementation comparison {label}")
165
+ try:
166
+ with tempfile.TemporaryDirectory(prefix=f".{label}-", dir=directory) as temporary:
167
+ staging = Path(temporary)
168
+ collected = collect_source(root, source, requested_ref, staging)
169
+ for name in ("git", "contents"):
170
+ destination = directory / name
171
+ if destination.exists() or destination.is_symlink():
172
+ raise ComparisonError(f"{label.capitalize()} content destination already exists")
173
+ os.replace(staging / name, destination)
174
+ record.update(collected)
175
+ except (OSError, ValueError) as exc:
176
+ record.update({"status": "unavailable", "limitations": [f"Initial {label} capture failed: {exc}"]})
177
+ record["state"] = "captured"
178
+ write_owned_object_atomic(path, _seal(record), artifact=f"implementation comparison {label}")
179
+ return _read_capture(root, directory, identity, record_name=record_name)[0]
180
+
181
+
182
+ def read_baseline_status(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> dict[str, Any]:
183
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
184
+ if not (directory / "baseline.json").exists():
185
+ return _response(root, directory, None, None, "Baseline was not captured")
186
+ with dir_flock(directory, ".comparison.lock"):
187
+ return _read_capture(root, directory, identity)[0]
188
+
189
+
190
+ def _read_capture(
191
+ root: Path, directory: Path, owner: dict[str, Any], *,
192
+ record_name: str = "baseline.json", budget: ReadBudget | None = None,
193
+ ) -> tuple[dict[str, Any], dict[str, Any] | None]:
194
+ label = record_name.removesuffix(".json")
195
+ path = directory / record_name
196
+ if not path.exists():
197
+ return _response(root, directory, None, None, f"{label.capitalize()} was not captured", record_name=record_name), None
198
+ try:
199
+ if path.is_symlink():
200
+ raise ValueError("Baseline record is a symbolic link")
201
+ snapshot = load_owned_object_snapshot(path, artifact="implementation comparison baseline", max_bytes=MAX_BASELINE_BYTES, budget=budget)
202
+ record = snapshot.value
203
+ if record.get("owner") != owner or record.get("projectRoot") != str(root):
204
+ raise ComparisonError("Baseline owner conflicts with its original capture")
205
+ unsealed = {key: value for key, value in record.items() if key != "recordDigest"}
206
+ expected = digest_bytes(json.dumps(unsealed, sort_keys=True, ensure_ascii=True).encode())
207
+ if record.get("recordDigest") != expected or record.get("schemaVersion") != "1.0":
208
+ raise ValueError("Baseline record digest or schema is invalid")
209
+ if record.get("status") not in {"complete", "partial", "unavailable"}:
210
+ raise ValueError("Baseline status is invalid")
211
+ _verify_contents(directory, record, budget=budget)
212
+ return _response(root, directory, record, digest_bytes(snapshot.raw_bytes), record_name=record_name), record
213
+ except ComparisonError:
214
+ raise
215
+ except (JsonBoundaryError, OSError, ValueError, KeyError, TypeError) as exc:
216
+ return _response(root, directory, None, None, f"Preserved {label} is unavailable: {exc}", record_name=record_name), None
217
+
218
+
219
+ def _verify_contents(directory: Path, record: dict[str, Any], *, budget: ReadBudget | None = None) -> None:
220
+ files = record.get("files")
221
+ if not isinstance(files, list) or len(files) > MAX_PATHS:
222
+ raise ValueError("Baseline source inventory is invalid")
223
+ source_budget = ReadBudget(MAX_TOTAL_READ_BYTES)
224
+ checked: set[str] = set()
225
+ for row in files:
226
+ relative = row.get("contentPath")
227
+ if relative is None or relative in checked:
228
+ continue
229
+ if not isinstance(relative, str) or relative != f"contents/{row.get('digest')}.txt":
230
+ raise ValueError("Baseline content reference is invalid")
231
+ body, _, problem = read_source_bytes(directory, relative, source_budget, shared_budget=budget)
232
+ if problem or body is None or digest_bytes(body) != row.get("digest"):
233
+ raise ValueError("Preserved source content changed or is incomplete")
234
+ checked.add(relative)
235
+ outputs = record.get("git", {})
236
+ git_bytes = 0
237
+ git_budget = ReadBudget(MAX_GIT_TOTAL_BYTES)
238
+ for output in outputs.values():
239
+ command_bytes = 0
240
+ for name in ("stdout", "stderr"):
241
+ reference = output[name]
242
+ relative = reference["path"]
243
+ if not isinstance(relative, str) or len(PurePosixPath(relative).parts) != 2 or PurePosixPath(relative).parts[0] != "git":
244
+ raise ValueError("Baseline Git content reference is invalid")
245
+ path = directory / relative
246
+ if path.is_symlink() or path.stat().st_size != reference["bytes"]:
247
+ raise ValueError("Preserved Git output changed")
248
+ command_bytes += reference["bytes"]
249
+ git_bytes += reference["bytes"]
250
+ if command_bytes > MAX_GIT_COMMAND_BYTES or git_bytes > MAX_GIT_TOTAL_BYTES:
251
+ raise ValueError("Preserved Git output exceeds its byte budget")
252
+ body, _, problem = read_source_bytes(directory, relative, git_budget, file_limit=MAX_GIT_COMMAND_BYTES, shared_budget=budget)
253
+ if problem or body is None or digest_bytes(body) != reference["storedDigest"]:
254
+ raise ValueError("Preserved Git output changed")
@@ -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
+ )