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