okstra 0.234.1 → 0.235.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli-registry.mjs +7 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
- package/dist/commands/implementation-report/implementation-report.mjs +73 -0
- package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
- package/dist/commands/trace/comparison.d.mts +39 -0
- package/dist/commands/trace/comparison.mjs +138 -0
- package/dist/commands/trace/comparison.mjs.map +1 -0
- package/dist/commands/trace/document.d.mts +8 -0
- package/dist/commands/trace/document.mjs +37 -0
- package/dist/commands/trace/document.mjs.map +1 -0
- package/dist/commands/trace/line-counts.d.mts +15 -0
- package/dist/commands/trace/line-counts.mjs +107 -0
- package/dist/commands/trace/line-counts.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +2 -1
- package/dist/commands/trace/model.mjs +13 -1
- package/dist/commands/trace/model.mjs.map +1 -1
- package/dist/commands/trace/progression.mjs +7 -3
- package/dist/commands/trace/progression.mjs.map +1 -1
- package/dist/commands/trace/task-link.d.mts +3 -0
- package/dist/commands/trace/task-link.mjs.map +1 -1
- package/dist/commands/trace/trace.mjs +64 -44
- package/dist/commands/trace/trace.mjs.map +1 -1
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +11 -5
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/types.d.mts +1 -0
- package/docs/architecture/storage-model.md +50 -0
- package/docs/cli.md +31 -15
- package/docs/project-structure-overview.md +6 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-tests-review.json +6 -0
- package/runtime/prompts/duties/test-reviewer.json +32 -0
- package/runtime/prompts/lead/report-writer.md +13 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
- package/runtime/python/okstra_ctl/code_review_census.py +38 -0
- package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
- package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
- package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
- package/runtime/python/okstra_ctl/code_review_target.py +16 -6
- package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
- package/runtime/python/okstra_ctl/consumers.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +6 -26
- package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
- package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
- package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
- package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
- package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
- package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
- package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
- package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
- package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
- package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
- package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
- package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
- package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
- package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
- package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
- package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
- package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
- package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
- package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
- package/runtime/python/okstra_ctl/json_boundary.py +28 -8
- package/runtime/python/okstra_ctl/paths.py +7 -4
- package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
- package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
- package/runtime/python/okstra_ctl/render.py +4 -0
- package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
- package/runtime/python/okstra_ctl/report_finalize.py +18 -4
- package/runtime/python/okstra_ctl/report_html/render.py +46 -7
- package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
- package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
- package/runtime/python/okstra_ctl/run.py +16 -0
- package/runtime/python/okstra_ctl/stage_done.py +11 -3
- package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
- package/runtime/python/okstra_ctl/stage_map.py +3 -3
- package/runtime/python/okstra_ctl/trace_review.py +1 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
- package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
- package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
- package/runtime/python/okstra_ctl/verification_generation.py +3 -2
- package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
- package/runtime/skills/okstra-code-review/SKILL.md +1 -1
- package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
- package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +31 -0
- package/runtime/skills/okstra-tdd/SKILL.md +74 -13
- package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
- package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
- package/runtime/templates/reports/html/i18n/en.json +113 -0
- package/runtime/templates/reports/html/i18n/ko.json +113 -0
- package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
- package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
- package/runtime/templates/trace/trace.template.md +2 -0
- package/runtime/validators/validate-report-views.py +4 -36
|
@@ -0,0 +1,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)})
|