okstra 0.234.1 → 0.236.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/host-registry-client.d.mts +9 -2
- package/dist/lib/host-registry-client.mjs +29 -3
- package/dist/lib/host-registry-client.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/runtime-payload.mjs +1 -0
- package/dist/lib/runtime-payload.mjs.map +1 -1
- package/dist/lib/types.d.mts +1 -0
- package/docs/architecture/storage-model.md +50 -0
- package/docs/architecture.md +1 -1
- package/docs/cli.md +37 -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/bin/lib/okstra/usage.sh +8 -8
- package/runtime/bin/okstra-qwen-exec.sh +5 -0
- package/runtime/prompts/duties/test-reviewer.json +32 -0
- package/runtime/prompts/lead/convergence.md +4 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +3 -3
- package/runtime/prompts/lead/report-writer.md +13 -1
- package/runtime/prompts/profiles/_common-contract.md +10 -1
- package/runtime/prompts/wizard/prompts.ko.json +16 -4
- package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
- package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
- package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
- package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
- package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
- package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
- package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
- package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
- 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/business_flow/contracts.py +11 -0
- package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
- package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
- package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
- package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
- 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/convergence.py +95 -5
- package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
- package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
- package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
- package/runtime/python/okstra_ctl/coverage_census.py +75 -12
- 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/entrypoints/hosts.py +1 -1
- 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/lead_progress.py +1 -1
- package/runtime/python/okstra_ctl/model_discovery.py +1 -1
- package/runtime/python/okstra_ctl/models.py +2 -2
- package/runtime/python/okstra_ctl/paths.py +7 -4
- package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
- package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
- 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/registry/provider_registry.py +1 -1
- package/runtime/python/okstra_ctl/render.py +4 -0
- package/runtime/python/okstra_ctl/render_final_report.py +1 -1
- 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 +17 -1
- package/runtime/python/okstra_ctl/run_context.py +18 -3
- package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
- 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/verdict_blocks.py +7 -2
- 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/python/okstra_ctl/wizard/engine.py +28 -1
- package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
- package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
- package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
- package/runtime/python/okstra_ctl/wizard/state.py +67 -20
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
- package/runtime/python/okstra_ctl/worker_audit_ledger.py +44 -8
- package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
- package/runtime/python/okstra_token_usage/claude.py +5 -1
- package/runtime/python/okstra_token_usage/collect.py +3 -3
- package/runtime/python/okstra_token_usage/pricing.py +1 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- 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-discussion/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +33 -2
- 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/templates/worker-prompt-preamble.md +12 -2
- package/runtime/validators/validate-report-views.py +4 -36
|
@@ -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)})
|
|
@@ -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")
|