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,129 @@
1
+ """Bounded JSON bridge for preserved implementation comparisons."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ from pathlib import Path
7
+ import re
8
+ import sys
9
+ from typing import Any
10
+
11
+ from ..json_boundary import PageBudgetExhausted, ReadBudget
12
+ from .model import MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES
13
+ from .baseline import (
14
+ MAX_BASELINE_RESPONSE_BYTES, MAX_OWNER_BYTES, ComparisonError,
15
+ _owner_and_directory, capture_baseline, read_baseline_status,
16
+ )
17
+ from .inputs import _validate_source, resolve_run_comparison, resolve_task_comparison
18
+ from .target import capture_target, capture_trace_target, read_target_status
19
+
20
+
21
+ def _read_source() -> dict[str, Any]:
22
+ raw = sys.stdin.buffer.read(MAX_COMPARISON_INPUT_BYTES + 1)
23
+ if len(raw) > MAX_COMPARISON_INPUT_BYTES:
24
+ raise ComparisonError("Comparison source stdin exceeds its byte limit")
25
+ source = json.loads(raw)
26
+ if not isinstance(source, dict):
27
+ raise ComparisonError("Comparison source stdin must be a JSON object")
28
+ return source
29
+
30
+
31
+ def _comparison_status(root: Path, directory: Path | None, owner: dict[str, Any]) -> dict[str, Any]:
32
+ from .publication import read_comparison_status
33
+
34
+ result = read_baseline_status(root, directory, owner)
35
+ try:
36
+ result["target"] = read_target_status(root, directory, owner)
37
+ except (OSError, ValueError) as exc:
38
+ result["target"] = {"status": "unavailable", "targetRef": None, "generation": None, "limitations": [str(exc)]}
39
+ try:
40
+ result["report"] = read_comparison_status(root, directory, owner)
41
+ except (OSError, ValueError) as exc:
42
+ result["report"] = {"status": "failed", "reportStatus": None, "dataPath": None, "htmlPath": None, "warnings": [str(exc)]}
43
+ return result
44
+
45
+
46
+ def _write_response(result: dict[str, Any]) -> None:
47
+ summaries = [result, *(result[key] for key in ("target", "report") if isinstance(result.get(key), dict))]
48
+ while len(json.dumps(result, ensure_ascii=True).encode()) + 1 > MAX_BASELINE_RESPONSE_BYTES:
49
+ for value in summaries:
50
+ field = next((key for key in ("limitations", "warnings") if value.get(key)), None)
51
+ if field:
52
+ value[field].pop()
53
+ value[field + "Omitted"] = True
54
+ break
55
+ else:
56
+ raise ComparisonError("Comparison response metadata exceeds its byte limit")
57
+ print(json.dumps(result, ensure_ascii=True))
58
+
59
+
60
+ def main(argv: list[str] | None = None) -> int:
61
+ parser = argparse.ArgumentParser()
62
+ parser.add_argument("action", choices=("capture", "capture-target", "status", "render"))
63
+ parser.add_argument("--project-root", type=Path)
64
+ parser.add_argument("--source-root", type=Path)
65
+ parser.add_argument("--comparison-dir", type=Path)
66
+ original = parser.add_mutually_exclusive_group(required=True)
67
+ original.add_argument("--owner-json")
68
+ original.add_argument("--run-manifest", type=Path)
69
+ parser.add_argument("--baseline-ref", default="")
70
+ parser.add_argument("--generation")
71
+ parser.add_argument("--scope", choices=("task",))
72
+ args = parser.parse_args(argv)
73
+ try:
74
+ if args.scope and (args.run_manifest is None or args.action not in {"render", "status"}):
75
+ raise ComparisonError("--scope task requires a stored --run-manifest render/status")
76
+ if args.run_manifest is not None:
77
+ if args.action not in {"render", "status"} or args.comparison_dir is not None:
78
+ raise ComparisonError("--run-manifest supports only stored render/status without --comparison-dir")
79
+ if args.project_root is None:
80
+ from okstra_project.resolver import ResolverError, resolve_project_root
81
+
82
+ try:
83
+ args.project_root = resolve_project_root(cwd=str(args.run_manifest.absolute().parent))
84
+ except ResolverError as exc:
85
+ raise ComparisonError(str(exc)) from exc
86
+ resolve_scope = resolve_task_comparison if args.scope == "task" else resolve_run_comparison
87
+ owner, args.comparison_dir = resolve_scope(args.project_root, args.run_manifest)
88
+ else:
89
+ if args.project_root is None:
90
+ raise ComparisonError("Comparison requires --project-root")
91
+ if len(args.owner_json.encode()) > MAX_OWNER_BYTES:
92
+ raise ComparisonError("Comparison owner exceeds its byte limit")
93
+ owner = json.loads(args.owner_json)
94
+ root, directory, owner = _owner_and_directory(args.project_root, args.comparison_dir, owner)
95
+ if args.action == "capture":
96
+ if args.source_root is None:
97
+ raise ComparisonError("Capture requires --source-root")
98
+ result = capture_baseline(root, args.source_root, directory,
99
+ owner, baseline_ref=args.baseline_ref)
100
+ elif args.action == "capture-target":
101
+ if args.source_root is None or not args.generation or re.fullmatch(r"[a-f0-9]{64}", args.generation) is None:
102
+ raise ComparisonError("Target capture requires --source-root and a 64-hex --generation")
103
+ source = _read_source()
104
+ if owner["kind"] == "trace":
105
+ capture_trace_target(root, args.source_root, directory, owner, source, generation=args.generation)
106
+ else:
107
+ if not _validate_source(root, owner, source, {}, ReadBudget(MAX_COMPARISON_READ_BYTES)):
108
+ raise ComparisonError("Comparison source no longer matches its saved original")
109
+ capture_target(root, args.source_root, directory, owner, generation=args.generation)
110
+ result = _comparison_status(root, directory, owner)
111
+ elif args.action == "render":
112
+ from .publication import publish_comparison
113
+
114
+ source = None if owner["kind"] in {"run", "task"} else _read_source()
115
+ try:
116
+ result = publish_comparison(root, directory, owner, source)
117
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
118
+ result = {"status": "failed", "reportStatus": None, "dataPath": None, "htmlPath": None, "warnings": [str(exc)]}
119
+ else:
120
+ result = _comparison_status(root, directory, owner)
121
+ _write_response(result)
122
+ return 0
123
+ except (OSError, ValueError, PageBudgetExhausted) as exc:
124
+ print(str(exc), file=sys.stderr)
125
+ return 1
126
+
127
+
128
+ if __name__ == "__main__":
129
+ raise SystemExit(main())
@@ -0,0 +1,340 @@
1
+ """Read preserved comparison facts and bind authored claims to their evidence."""
2
+ from __future__ import annotations
3
+
4
+ from collections.abc import Mapping
5
+ from dataclasses import dataclass
6
+ import json
7
+ from pathlib import Path
8
+ import time
9
+ from typing import Any
10
+
11
+ from ..json_boundary import PageBudgetExhausted, ReadBudget
12
+ from .baseline import (
13
+ ComparisonError, ComparisonOwner, _owner_and_directory,
14
+ _read_capture,
15
+ )
16
+ from .source import GIT_TIMEOUT_SECONDS, MAX_FILE_READ_BYTES, GitCollector, digest_bytes
17
+ from .commit_source import read_recorded_commit_source
18
+ from .business_reuse import read_matching_business_explanations
19
+ from .target import _current_target
20
+ from .inputs import _ChangedInput, _artifact_bytes, _validate_source, read_comparison_before_commit
21
+ from .model import ComparisonSource, MAX_COMPARISON_INPUT_BYTES, MAX_COMPARISON_READ_BYTES, MAX_RECORDS, RunEvidenceSelection, TaskEvidenceSelection
22
+ from .run_evidence import read_run_evidence
23
+
24
+ MAX_CHANGES = 200
25
+ MAX_EXCERPT_LINES = 80
26
+ MAX_EXCERPT_BYTES = 8192
27
+ MAX_TOTAL_EXCERPT_BYTES = 1024 * 1024
28
+ MAX_ASSEMBLY_BYTES = 8 * 1024 * 1024
29
+ CLAIM_FIELDS = ("before", "after", "cause", "principle", "impact")
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Assembly:
34
+ data: dict[str, Any]
35
+ fingerprints: dict[str, str | None]
36
+ selection: RunEvidenceSelection | TaskEvidenceSelection | None = None
37
+ captures: dict[str, tuple[Path, dict[str, Any] | None]] | None = None
38
+
39
+
40
+ def comparison_fingerprints(project_root: Path, fingerprints: Mapping[str, str | None]) -> dict[str, str | None]:
41
+ observed: dict[str, str | None] = {}
42
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES)
43
+ for path in fingerprints:
44
+ _artifact_bytes(Path(project_root).resolve(strict=True), path, observed, budget)
45
+ return observed
46
+
47
+
48
+ def _capture_inputs(root: Path, directory: Path, record: dict[str, Any] | None, fingerprints: dict[str, str | None]) -> None:
49
+ if record is None:
50
+ return
51
+ for row in record["files"]:
52
+ if row.get("contentPath"):
53
+ fingerprints[(directory / row["contentPath"]).relative_to(root).as_posix()] = row["digest"]
54
+ for output in record.get("git", {}).values():
55
+ for stream in ("stdout", "stderr"):
56
+ reference = output[stream]
57
+ fingerprints[(directory / reference["path"]).relative_to(root).as_posix()] = reference["storedDigest"]
58
+
59
+
60
+ def _file_changes(before: dict[str, Any] | None, after: dict[str, Any] | None) -> list[dict[str, Any]]:
61
+ sides = [{row["path"]: row for row in capture.get("files", [])} if capture else {} for capture in (before, after)]
62
+ results = []
63
+ for path in sorted(sides[0].keys() | sides[1].keys()):
64
+ rows = [side.get(path) for side in sides]
65
+ absent = [row.get("status") == "missing" if row else bool(capture and capture.get("completeInventory")) for row, capture in zip(rows, (before, after))]
66
+ digests = [row.get("digest") if row and row.get("status") == "complete" else None for row in rows]
67
+ change = "unknown"
68
+ if absent[0] and digests[1]:
69
+ change = "added"
70
+ elif absent[1] and digests[0]:
71
+ change = "removed"
72
+ elif all(digests):
73
+ modes = [row.get("mode") for row in rows]
74
+ if any(capture and capture.get("reconstruction") == "recorded-commit" for capture in (before, after)):
75
+ modes = [mode & 0o100 if type(mode) is int else mode for mode in modes]
76
+ change = "unchanged" if digests[0] == digests[1] and modes[0] == modes[1] else "modified"
77
+ results.append({"path": path, "change": change, "kind": next((row.get("kind") for row in reversed(rows) if row), None),
78
+ "beforeDigest": digests[0], "afterDigest": digests[1]})
79
+ return results
80
+
81
+
82
+ def _record_evidence(source: Mapping[str, Any]) -> list[dict[str, Any]]:
83
+ rows = []
84
+ identifiers: set[str] = set()
85
+ for record in source.get("evidence", []):
86
+ identifier = record.get("id")
87
+ if not isinstance(identifier, str) or not identifier or identifier in identifiers:
88
+ raise ComparisonError("Comparison record identifiers must be unique nonempty strings")
89
+ if identifier.startswith("execution:"):
90
+ raise ComparisonError("Comparison records reserve the execution: identifier namespace")
91
+ if any(not isinstance(record[key], str) for key in ("label", "command", "summary", "recordedAt", "failureCause", "step", "recordType") if key in record) or ("exitCode" in record and record["exitCode"] is not None and type(record["exitCode"]) is not int):
92
+ raise ComparisonError("Comparison record fields are invalid")
93
+ identifiers.add(identifier)
94
+ row = {key: record[key] for key in ("label", "command", "exitCode", "summary", "recordedAt", "failureCause", "step", "recordType") if key in record}
95
+ row.update(id="record:" + identifier, recordId=identifier)
96
+ row.update(kind="record", origin="agent-recorded", support="partial", targetBound=False,
97
+ limitations=["Recorded by a session; execution target attribution is not established"])
98
+ rows.append(row)
99
+ return rows
100
+
101
+
102
+ def _source_evidence(reference: dict[str, Any], captures: dict[str, tuple[Path, dict[str, dict[str, Any]]]], root: Path, fingerprints: dict[str, str | None], budget: ReadBudget, excerpt_budget: ReadBudget, *, before_contents: Mapping[str, bytes] | None = None) -> dict[str, Any]:
103
+ if set(reference) != {"side", "path", "startLine", "endLine"} or reference["side"] not in captures or not isinstance(reference["path"], str):
104
+ raise ValueError("Source evidence reference is invalid")
105
+ start, end = reference["startLine"], reference["endLine"]
106
+ if type(start) is not int or type(end) is not int or start < 1 or end < start or end - start >= MAX_EXCERPT_LINES:
107
+ raise ValueError("Source evidence exceeds its line range")
108
+ directory, files = captures[reference["side"]]
109
+ row = files.get(reference["path"])
110
+ result = {**reference, "kind": "source", "origin": "source-inspected", "support": "unverified",
111
+ "digest": None, "excerpt": "", "limitations": []}
112
+ reconstructed = before_contents is not None and reference["side"] == "before"
113
+ if not row or row.get("kind") != "text" or not (row.get("contentPath") or reconstructed):
114
+ result["limitations"].append("Preserved text is unavailable for this reference")
115
+ return result
116
+ if reconstructed:
117
+ body = before_contents.get(reference["path"])
118
+ result["reconstruction"] = "recorded-commit"
119
+ result["limitations"].append("Reconstructed commit text does not establish the original uncommitted state")
120
+ else:
121
+ relative = (directory / row["contentPath"]).relative_to(root).as_posix()
122
+ body = _artifact_bytes(root, relative, fingerprints, budget, limit=MAX_FILE_READ_BYTES)
123
+ if body is None or digest_bytes(body) != row["digest"]:
124
+ raise ComparisonError("Preserved source evidence changed")
125
+ lines = body.decode("utf-8").splitlines(keepends=True)
126
+ if end > len(lines):
127
+ result["limitations"].append("Referenced lines are outside preserved content")
128
+ return result
129
+ excerpt = "".join(lines[start - 1:end]).encode()
130
+ available = min(MAX_EXCERPT_BYTES, excerpt_budget.max_bytes - excerpt_budget.bytes_read)
131
+ if len(excerpt) > available:
132
+ result["limitations"].append("Source excerpt was truncated to its byte limit")
133
+ excerpt = excerpt[:available]
134
+ excerpt_budget.bytes_read += len(excerpt)
135
+ result.update(digest=row["digest"], excerpt=excerpt.decode("utf-8", errors="ignore"), support="partial" if excerpt else "unverified")
136
+ return result
137
+
138
+
139
+ def _load_notes(raw: bytes | None, owner: dict[str, Any], baseline: dict[str, Any], target: dict[str, Any]) -> list[dict[str, Any]]:
140
+ if raw is None:
141
+ raise ValueError("Comparison notes are missing")
142
+ if len(raw) > MAX_COMPARISON_INPUT_BYTES:
143
+ raise ValueError("Comparison notes exceed their byte limit")
144
+ try:
145
+ notes = json.loads(raw)
146
+ except RecursionError as exc:
147
+ raise ValueError("Comparison notes exceed their JSON nesting limit") from exc
148
+ if not isinstance(notes, dict) or set(notes) != {"schemaVersion", "owner", "baselineRef", "targetRef", "changes"}:
149
+ raise ValueError("Comparison notes fields are invalid")
150
+ if notes["schemaVersion"] != "1.0" or notes["owner"] != owner:
151
+ raise ValueError("Comparison notes owner or schema is invalid")
152
+ if notes["baselineRef"] != baseline.get("baselineRef") or notes["targetRef"] != target.get("targetRef"):
153
+ raise ValueError("Comparison notes do not match the preserved baseline and target")
154
+ changes = notes["changes"]
155
+ if not isinstance(changes, list) or len(changes) > MAX_CHANGES:
156
+ raise ValueError("Comparison change list is invalid")
157
+ return changes
158
+
159
+
160
+ def _normalize_changes(changes: list[dict[str, Any]], captures: dict[str, tuple[Path, dict[str, Any] | None]], root: Path, fingerprints: dict[str, str | None], budget: ReadBudget, evidence: list[dict[str, Any]], source: ComparisonSource, *, before_contents: Mapping[str, bytes] | None = None) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
161
+ records = {row["recordId"]: row for row in evidence}
162
+ ledger = {row["id"]: row for row in evidence}
163
+ files = {side: (directory, {row["path"]: row for row in record.get("files", [])} if record else {}) for side, (directory, record) in captures.items()}
164
+ excerpt_budget = ReadBudget(MAX_TOTAL_EXCERPT_BYTES)
165
+ source_ids = {
166
+ key: {str(row if isinstance(row, str) else row.get("id", row.get("requirementId", row.get("useCaseId")))) for row in source.get(key, [])}
167
+ for key in ("requirements", "useCases")
168
+ }
169
+ owner = source["owner"]
170
+ source_ids["stages"] = {str(stage) for stage in source.get("stages", [owner["stage"]] if owner.get("stage") else [])}
171
+ source_refs: dict[str, str] = {}
172
+ source_rows = []
173
+ normalized = []
174
+ identifiers: set[str] = set()
175
+ for change in changes:
176
+ fields = {"id", "title", "scenario", "input", "affected", "requirements", "useCases", "stages", "limitations", *CLAIM_FIELDS}
177
+ if not isinstance(change, dict) or set(change) != fields:
178
+ raise ValueError("Comparison change fields are invalid")
179
+ if any(not isinstance(change[key], str) or not change[key].strip() for key in ("id", "title", "scenario", "input")) or change["id"] in identifiers:
180
+ raise ValueError("Comparison change text is invalid")
181
+ identifiers.add(change["id"])
182
+ output = {key: value for key, value in change.items() if key not in CLAIM_FIELDS}
183
+ for key in ("affected", "requirements", "useCases", "stages", "limitations"):
184
+ values = change[key]
185
+ if not isinstance(values, list) or len(values) > MAX_RECORDS or any(not isinstance(value, str) and not (key == "stages" and type(value) is int and value > 0) for value in values):
186
+ raise ValueError("Comparison change links are invalid")
187
+ output["limitations"] = list(output["limitations"])
188
+ for key in ("requirements", "useCases", "stages"):
189
+ unknown = [value for value in change[key] if str(value) not in source_ids[key]]
190
+ if unknown:
191
+ output["limitations"].append(f"Unverified {key} links were excluded: {unknown}")
192
+ output[key] = [value for value in change[key] if value not in unknown]
193
+ for key in CLAIM_FIELDS:
194
+ claim = change[key]
195
+ if not isinstance(claim, dict) or set(claim) != {"text", "evidence"} or not isinstance(claim["text"], str) or not claim["text"].strip() or not isinstance(claim["evidence"], list) or len(claim["evidence"]) > MAX_RECORDS:
196
+ raise ValueError("Authored claims may contain only text and evidence references")
197
+ links = []
198
+ for reference in claim["evidence"]:
199
+ if not isinstance(reference, dict):
200
+ raise ValueError("Comparison evidence reference must be an object")
201
+ if set(reference) == {"recordId"}:
202
+ if reference["recordId"] not in records:
203
+ raise ValueError("Comparison record reference is unavailable")
204
+ links.append(records[reference["recordId"]]["id"])
205
+ else:
206
+ identity = json.dumps(reference, sort_keys=True)
207
+ if identity not in source_refs:
208
+ row = _source_evidence(reference, files, root, fingerprints, budget, excerpt_budget, before_contents=before_contents)
209
+ row["id"] = "source-" + digest_bytes(identity.encode())[:16]
210
+ source_refs[identity] = row["id"]
211
+ source_rows.append(row)
212
+ ledger[row["id"]] = row
213
+ links.append(source_refs[identity])
214
+ linked = [ledger[identifier] for identifier in links]
215
+ origins = {row["origin"] for row in linked}
216
+ if not origins:
217
+ origin = "expected"
218
+ elif len(origins) == 1:
219
+ origin = next(iter(origins))
220
+ else:
221
+ origin = "mixed"
222
+ unbound = any(row["origin"] == "runner-observed" and not row["targetBound"] for row in linked)
223
+ if unbound:
224
+ output["limitations"].append("Execution evidence is not bound to the preserved target")
225
+ output[key] = {"text": claim["text"], "evidence": links, "origin": origin,
226
+ "support": "partial" if linked and not unbound and all(row["support"] == "partial" for row in linked) else "unverified"}
227
+ normalized.append(output)
228
+ return normalized, source_rows
229
+
230
+
231
+ def assemble_comparison(
232
+ project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner, source: ComparisonSource, *,
233
+ budget: ReadBudget | None = None, git: GitCollector | None = None,
234
+ ) -> Assembly:
235
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
236
+ fingerprints: dict[str, str | None] = {}
237
+ budget = ReadBudget(MAX_COMPARISON_READ_BYTES) if budget is None else budget
238
+ selection: RunEvidenceSelection | None = None
239
+ data: dict[str, Any] = {"schemaVersion": "1.0", "status": "stale", "source": dict(source),
240
+ "baseline": {}, "target": {}, "changes": [], "evidence": [],
241
+ "coverage": {"files": [], "unexplained": [], "unobserved": [], "excluded": []},
242
+ "limitations": []}
243
+ try:
244
+ if not _validate_source(root, identity, source, fingerprints, budget):
245
+ data["limitations"].append("Normalized source does not match the saved original; normalize it again")
246
+ return Assembly(data, fingerprints)
247
+ data["limitations"].extend(source.get("limitations", []))
248
+ baseline, before = _read_capture(root, directory, identity, budget=budget)
249
+ target, after, target_fingerprints = _current_target(root, directory, identity, budget=budget)
250
+ fingerprints.update(target_fingerprints)
251
+ runner = None
252
+ if identity["kind"] == "run":
253
+ runner = read_run_evidence(root, identity, after, budget=budget, fingerprints=fingerprints)
254
+ selection = runner.selection
255
+ data["limitations"].extend(runner.limitations)
256
+ if target.get("generation") != runner.generation:
257
+ after = None
258
+ target = {**target, "status": "unavailable", "generation": runner.generation, "targetRef": None,
259
+ "limitations": ["Stored target does not match the current completed verification generation"]}
260
+ if baseline.get("baselineRef"):
261
+ fingerprints[baseline["baselineRef"]["path"]] = baseline["baselineRef"]["digest"]
262
+ target_dir = directory / "targets" / target["generation"] if target.get("generation") else directory
263
+ for capture_dir, name, record in ((directory, "baseline.json", before), (target_dir, "target.json", after)):
264
+ _artifact_bytes(root, (capture_dir / name).relative_to(root).as_posix(), fingerprints, budget)
265
+ _capture_inputs(root, capture_dir, record, fingerprints)
266
+ _artifact_bytes(root, (directory / "target-current.json").relative_to(root).as_posix(), fingerprints, budget)
267
+ before_contents = None
268
+ if before is None and fingerprints.get((directory / "baseline.json").relative_to(root).as_posix()) is None:
269
+ try:
270
+ commit = read_comparison_before_commit(root, identity, budget=budget, fingerprints=fingerprints)
271
+ if commit is not None:
272
+ if git is None:
273
+ git = GitCollector(shared_budget=budget, deadline=time.monotonic() + GIT_TIMEOUT_SECONDS)
274
+ restored = read_recorded_commit_source(root, commit, git=git)
275
+ before, before_contents = restored.record, restored.contents
276
+ baseline = {**baseline, "status": before["status"],
277
+ "limitations": baseline["limitations"] + before["limitations"]}
278
+ except _ChangedInput:
279
+ raise
280
+ except (OSError, ValueError) as exc:
281
+ baseline["limitations"].append(f"Recorded before source is unavailable: {exc}")
282
+ fields = ("status", "capturedAt", "head", "baselineCommit", "limitations", "scope", "completeInventory", "reconstruction", "dirtyState")
283
+ data["baseline"] = {**{key: before.get(key) for key in fields if before and key in before}, "ref": baseline.get("baselineRef"), "status": baseline["status"], "limitations": baseline["limitations"]}
284
+ data["target"] = {**{key: after.get(key) for key in fields if after and key in after}, "ref": target.get("targetRef"), "status": target["status"], "generation": target["generation"], "limitations": target["limitations"]}
285
+ data["evidence"] = _record_evidence(source)
286
+ data["source"]["evidence"] = [dict(row) for row in data["evidence"]]
287
+ if runner is not None:
288
+ data["evidence"].extend(runner.rows)
289
+ business, business_limitations = read_matching_business_explanations(
290
+ root, source, {"before": (directory, before), "after": (target_dir, after)},
291
+ budget=budget, fingerprints=fingerprints,
292
+ )
293
+ data["evidence"].extend(business)
294
+ data["limitations"].extend(business_limitations)
295
+ partial = baseline["status"] != "complete" or target["status"] != "complete" or bool(source.get("limitations")) or bool(runner and runner.limitations) or bool(business_limitations)
296
+ try:
297
+ raw = _artifact_bytes(root, (directory / "notes.json").relative_to(root).as_posix(), fingerprints, budget, limit=MAX_COMPARISON_INPUT_BYTES)
298
+ changes = _load_notes(raw, identity, baseline, target)
299
+ changes, source_rows = _normalize_changes(changes, {"before": (directory, before), "after": (target_dir, after)}, root, fingerprints, budget, data["evidence"], source, before_contents=before_contents)
300
+ except _ChangedInput:
301
+ raise
302
+ except (ValueError, KeyError, TypeError) as exc:
303
+ data["limitations"].append(f"Comparison notes were not used: {exc}")
304
+ partial = True
305
+ else:
306
+ data["changes"] = changes
307
+ data["evidence"].extend(source_rows)
308
+ except _ChangedInput as exc:
309
+ data["limitations"].append(str(exc))
310
+ return Assembly(data, fingerprints, selection)
311
+ except PageBudgetExhausted as exc:
312
+ data["status"] = "partial"
313
+ data["changes"] = []
314
+ for side in ("baseline", "target"):
315
+ if not data[side]:
316
+ data[side] = {"status": "unavailable", "ref": None, "limitations": [str(exc)]}
317
+ data["limitations"].append(str(exc))
318
+ return Assembly(data, fingerprints, selection)
319
+ files = _file_changes(before, after)
320
+ observed = {row["path"] for row in files if row["change"] in {"added", "removed", "modified"}}
321
+ evidence_paths = {row["id"]: row["path"] for row in data["evidence"] if row["kind"] == "source"}
322
+ linked_paths = {change["id"]: {evidence_paths[identifier] for key in CLAIM_FIELDS for identifier in change[key]["evidence"] if identifier in evidence_paths} for change in data["changes"]}
323
+ explained = {path for paths in linked_paths.values() for path in paths}
324
+ data["coverage"] = {"files": files, "unexplained": sorted(observed - explained),
325
+ "unobserved": [change["id"] for change in data["changes"] if not observed.intersection(linked_paths[change["id"]])],
326
+ "excluded": sorted(set((before or {}).get("excludedParts", [])) | set((after or {}).get("excludedParts", [])))}
327
+ data["limitations"].extend(baseline["limitations"] + target["limitations"])
328
+ data["limitations"].append("Evidence presence does not prove natural-language claims; source inspection is not execution verification")
329
+ partial = partial or any(change["limitations"] for change in data["changes"])
330
+ data["status"] = "partial" if partial else "ready"
331
+ if len(json.dumps(data, ensure_ascii=True).encode()) > MAX_ASSEMBLY_BYTES:
332
+ data["changes"], data["evidence"] = [], []
333
+ data["coverage"] = {"files": [], "unexplained": [], "unobserved": [], "excluded": []}
334
+ for side in ("baseline", "target"):
335
+ data[side] = {key: value for key, value in data[side].items() if key in {"ref", "status", "generation", "limitations"}}
336
+ data["limitations"].append("Detailed comparison exceeded the serialized data byte limit")
337
+ data["status"] = "partial"
338
+ if len(json.dumps(data, ensure_ascii=True).encode()) > MAX_ASSEMBLY_BYTES:
339
+ raise ComparisonError("Comparison metadata exceeds its serialized byte limit")
340
+ return Assembly(data, fingerprints, selection, {"before": (directory, before), "after": (target_dir, after)})