okstra 0.234.1 → 0.235.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +7 -3
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +64 -44
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  99. package/runtime/skills/okstra-run/SKILL.md +31 -0
  100. package/runtime/skills/okstra-tdd/SKILL.md +74 -13
  101. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  102. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  103. package/runtime/templates/reports/html/i18n/en.json +113 -0
  104. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  105. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  106. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  107. package/runtime/templates/trace/trace.template.md +2 -0
  108. package/runtime/validators/validate-report-views.py +4 -36
@@ -0,0 +1,144 @@
1
+ """Generation-bound immutable implementation targets."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+ from collections.abc import Mapping
6
+ import json
7
+ import os
8
+ import re
9
+ from typing import Any
10
+
11
+ from ..json_boundary import ReadBudget, load_owned_object_snapshot, write_owned_object_atomic
12
+ from ..run_context import dir_flock
13
+ from ..trace_tasks import read_trace_source, trace_integration_completed
14
+ from .baseline import (
15
+ MAX_BASELINE_RESPONSE_BYTES, ComparisonError, ComparisonOwner, _capture_source_record, _owner_and_directory,
16
+ _read_capture, _response,
17
+ )
18
+ from .source import digest_bytes
19
+ from .inputs import _validate_source
20
+ from .model import MAX_COMPARISON_READ_BYTES
21
+
22
+ GENERATION_PATTERN = re.compile(r"[a-f0-9]{64}\Z")
23
+
24
+
25
+ def _target_directory(directory: Path, generation: str) -> Path:
26
+ if not isinstance(generation, str) or not GENERATION_PATTERN.fullmatch(generation):
27
+ raise ComparisonError("Target generation must be a settled input SHA-256")
28
+ path = directory
29
+ for part in ("targets", generation):
30
+ path /= part
31
+ if path.is_symlink():
32
+ raise ComparisonError("Target paths must not follow symbolic links")
33
+ return path
34
+
35
+
36
+ def _read_target_pointer(directory: Path, owner: dict[str, Any], *, budget: ReadBudget | None = None) -> tuple[dict[str, Any] | None, str | None]:
37
+ path = directory / "target-current.json"
38
+ if not path.exists() and not path.is_symlink():
39
+ return None, None
40
+ if path.is_symlink():
41
+ raise ComparisonError("Target pointer must not follow symbolic links")
42
+ snapshot = load_owned_object_snapshot(path, artifact="implementation target pointer", max_bytes=16 * 1024, budget=budget)
43
+ pointer = snapshot.value
44
+ if pointer.get("owner") != owner or pointer.get("schemaVersion") != "1.0":
45
+ raise ComparisonError("Target pointer owner is invalid")
46
+ _target_directory(directory, pointer.get("generation"))
47
+ if not isinstance(pointer.get("sourceRoot"), str):
48
+ raise ComparisonError("Target pointer source is invalid")
49
+ return pointer, digest_bytes(snapshot.raw_bytes)
50
+
51
+
52
+ def _target_result(root: Path, directory: Path, generation: str | None, response: dict[str, Any]) -> dict[str, Any]:
53
+ result = {
54
+ **response, "directory": directory.relative_to(root).as_posix(),
55
+ "notesPath": (directory / "notes.json").relative_to(root).as_posix(),
56
+ "generation": generation,
57
+ "targetRef": response.get("targetRef") if response["status"] != "unavailable" else None,
58
+ }
59
+ while len(json.dumps(result, ensure_ascii=True).encode()) + 1 > MAX_BASELINE_RESPONSE_BYTES:
60
+ if not result["limitations"]:
61
+ raise ComparisonError("Target response metadata exceeds its byte limit")
62
+ result["limitations"].pop()
63
+ result["limitationsOmitted"] = True
64
+ return result
65
+
66
+
67
+ def _current_target(root: Path, directory: Path, owner: dict[str, Any], *, budget: ReadBudget | None = None) -> tuple[dict[str, Any], dict[str, Any] | None, dict[str, str | None]]:
68
+ pointer, pointer_digest = _read_target_pointer(directory, owner, budget=budget)
69
+ fingerprints = {(directory / "target-current.json").relative_to(root).as_posix(): pointer_digest}
70
+ if pointer is None:
71
+ return _target_result(root, directory, None, _response(
72
+ root, directory, None, None, "Target was not captured", record_name="target.json",
73
+ )), None, fingerprints
74
+ generation = pointer["generation"]
75
+ response, record = _read_capture(root, _target_directory(directory, generation), owner, record_name="target.json", budget=budget)
76
+ if response.get("targetRef"):
77
+ fingerprints[response["targetRef"]["path"]] = response["targetRef"]["digest"]
78
+ if record is not None and (record.get("generation") != generation or record.get("sourceRoot") != pointer["sourceRoot"]):
79
+ raise ComparisonError("Target generation conflicts with its original capture")
80
+ return _target_result(root, directory, generation, response), record, fingerprints
81
+
82
+
83
+ def capture_target(
84
+ project_root: Path, source_root: Path, comparison_dir: Path | None,
85
+ owner: ComparisonOwner, *, generation: str,
86
+ ) -> dict[str, Any]:
87
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
88
+ if owner["kind"] not in {"run", "trace"}:
89
+ raise ComparisonError("Target capture requires a run or trace owner")
90
+ target_dir = _target_directory(directory, generation)
91
+ source = Path(source_root).resolve()
92
+ directory.mkdir(parents=True, exist_ok=True)
93
+ with dir_flock(directory, ".comparison.lock"):
94
+ pointer, _ = _read_target_pointer(directory, identity)
95
+ if pointer is None and owner["kind"] == "trace" and (directory / "targets").exists():
96
+ with os.scandir(directory / "targets") as reservations:
97
+ if any(entry.name != generation for entry in reservations):
98
+ raise ComparisonError("Trace target generation was already reserved")
99
+ if pointer is not None and owner["kind"] == "trace" and pointer["generation"] != generation:
100
+ raise ComparisonError("Trace target generation is already fixed")
101
+ existing = (target_dir / "target.json").exists() or (target_dir / "target.json").is_symlink()
102
+ if existing and pointer is None:
103
+ raise ComparisonError("Target generation has no current pointer")
104
+ if target_dir.exists() and not existing:
105
+ if pointer is not None and pointer["generation"] == generation and pointer["sourceRoot"] != str(source):
106
+ raise ComparisonError("Target source conflicts with its original capture")
107
+ response, _ = _read_capture(root, target_dir, identity, record_name="target.json")
108
+ return _target_result(root, directory, generation, response)
109
+ if not existing:
110
+ target_dir.mkdir(parents=True, exist_ok=True)
111
+ write_owned_object_atomic(directory / "target-current.json", {
112
+ "schemaVersion": "1.0", "owner": identity,
113
+ "generation": generation, "sourceRoot": str(source),
114
+ }, artifact="implementation target pointer")
115
+ response = _capture_source_record(
116
+ root, source, target_dir, identity, "", record_name="target.json",
117
+ metadata={"generation": generation},
118
+ )
119
+ return _target_result(root, directory, generation, response)
120
+
121
+
122
+ def capture_trace_target(
123
+ project_root: Path, source_root: Path, comparison_dir: Path | None,
124
+ owner: ComparisonOwner, source: Mapping[str, Any], *, generation: str,
125
+ ) -> dict[str, Any]:
126
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
127
+ if identity["kind"] != "trace":
128
+ raise ComparisonError("Trace target capture requires a trace owner")
129
+ if not _validate_source(root, identity, source, {}, ReadBudget(MAX_COMPARISON_READ_BYTES)):
130
+ raise ComparisonError("Comparison source no longer matches its saved original")
131
+ trace = read_trace_source(root, identity["path"])
132
+ if trace.digest != source["digest"] or trace.digest != generation:
133
+ raise ComparisonError("Trace target generation must match its saved original digest")
134
+ if not trace_integration_completed(trace.frontmatter):
135
+ raise ComparisonError("Trace target requires its saved completed integration")
136
+ return capture_target(root, source_root, directory, identity, generation=generation)
137
+
138
+
139
+ def read_target_status(project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner) -> dict[str, Any]:
140
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
141
+ if not (directory / "target-current.json").exists() and not (directory / "target-current.json").is_symlink():
142
+ return _current_target(root, directory, identity)[0]
143
+ with dir_flock(directory, ".comparison.lock"):
144
+ return _current_target(root, directory, identity)[0]
@@ -0,0 +1,333 @@
1
+ """Compose whole-task views from the selected stages' preserved comparisons."""
2
+ from __future__ import annotations
3
+
4
+ from copy import deepcopy
5
+ import json
6
+ from pathlib import Path
7
+ import time
8
+ from typing import Any
9
+
10
+ from ..final_report_paths import final_report_data_path
11
+ from ..json_boundary import PageBudgetExhausted, ReadBudget, parse_owned_snapshot
12
+ from .assembly import (
13
+ Assembly, CLAIM_FIELDS, MAX_ASSEMBLY_BYTES, MAX_CHANGES, _capture_inputs,
14
+ _file_changes, assemble_comparison,
15
+ )
16
+ from .baseline import ComparisonError, ComparisonOwner, _owner_and_directory, _read_capture
17
+ from .commit_source import read_recorded_commit_source, recorded_commit_is_ancestor
18
+ from .inputs import (
19
+ _ChangedInput, _artifact_bytes, _validate_source, read_run_comparison_source,
20
+ run_comparison_scope,
21
+ )
22
+ from .model import ComparisonSource, MAX_RECORDS, TaskEvidenceSelection
23
+ from .source import GIT_TIMEOUT_SECONDS, MAX_PATHS, GitCollector, digest_bytes
24
+ from .task_selection import SelectedTaskStage, TaskComparisonSelection
25
+
26
+
27
+ def _merge_fingerprints(target: dict[str, str | None], observed: dict[str, str | None]) -> None:
28
+ for path, digest in observed.items():
29
+ if path in target and target[path] != digest:
30
+ raise _ChangedInput(f"Task comparison input changed during assembly: {path}")
31
+ target[path] = digest
32
+
33
+
34
+ def _evidence_rows(stage: int, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
35
+ prefix = f"stage{stage}:"
36
+ evidence = []
37
+ for row in rows:
38
+ output = {**row, "id": prefix + row["id"], "stage": stage}
39
+ if "recordId" in row:
40
+ output["recordId"] = prefix + row["recordId"]
41
+ evidence.append(output)
42
+ return evidence
43
+
44
+
45
+ def _stage_rows(stage: int, data: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
46
+ prefix = f"stage{stage}:"
47
+ evidence = _evidence_rows(stage, data["evidence"])
48
+ changes = []
49
+ for change in data["changes"]:
50
+ output = deepcopy(change)
51
+ output.update(id=prefix + change["id"], stage=stage)
52
+ for field in CLAIM_FIELDS:
53
+ output[field]["evidence"] = [prefix + identifier for identifier in change[field]["evidence"]]
54
+ changes.append(output)
55
+ return changes, evidence
56
+
57
+
58
+ def _coverage_union(stages: dict[int, Assembly]) -> dict[str, Any]:
59
+ files: dict[str, dict[str, Any]] = {}
60
+ unexplained: set[str] = set()
61
+ unobserved: list[str] = []
62
+ excluded: set[str] = set()
63
+ for stage, assembled in stages.items():
64
+ coverage = assembled.data["coverage"]
65
+ unexplained.update(coverage["unexplained"])
66
+ unobserved.extend(f"stage{stage}:{identifier}" for identifier in coverage["unobserved"])
67
+ excluded.update(coverage["excluded"])
68
+ for row in coverage["files"]:
69
+ path = row["path"]
70
+ if path not in files and len(files) >= MAX_PATHS:
71
+ raise ComparisonError("Whole-task coverage path limit reached")
72
+ observation = {"stage": stage, **{key: row[key] for key in ("change", "beforeDigest", "afterDigest")}}
73
+ if path not in files:
74
+ files[path] = {**row, "stageObservations": [observation]}
75
+ else:
76
+ previous = files[path]
77
+ if any(previous[key] != row[key] for key in ("change", "beforeDigest", "afterDigest")):
78
+ previous.update(change="unknown", beforeDigest=None, afterDigest=None)
79
+ previous["stageObservations"].append(observation)
80
+ return {"files": [files[path] for path in sorted(files)], "unexplained": sorted(unexplained),
81
+ "unobserved": unobserved, "excluded": sorted(excluded)}
82
+
83
+
84
+ def _same_source(left: dict[str, Any], right: dict[str, Any]) -> bool:
85
+ if not all(record.get("completeInventory") is True for record in (left, right)):
86
+ return False
87
+ if set(left.get("excludedParts", [])) != set(right.get("excludedParts", [])):
88
+ return False
89
+ tracked = [{row["path"] for row in record["files"] if row.get("tracked")} for record in (left, right)]
90
+ return tracked[0] == tracked[1] and all(row["change"] == "unchanged" for row in _file_changes(left, right))
91
+
92
+
93
+ def _preserved_index_identity(record: dict[str, Any]) -> tuple[str, int] | None:
94
+ identities = []
95
+ outputs = record.get("git", {})
96
+ for name in ("index-before", "index-after"):
97
+ output = outputs.get(name)
98
+ if not isinstance(output, dict) or output.get("complete") is not True or output.get("returncode") != 0:
99
+ return None
100
+ stdout = output.get("stdout")
101
+ if not isinstance(stdout, dict) or not isinstance(stdout.get("storedDigest"), str) or type(stdout.get("bytes")) is not int or stdout["bytes"] < 0:
102
+ return None
103
+ identities.append((stdout["storedDigest"], stdout["bytes"]))
104
+ return identities[0] if identities[0] == identities[1] else None
105
+
106
+
107
+ def _integrated_target(
108
+ root: Path, before: dict[str, Any] | None, stages: dict[int, Assembly],
109
+ selected_heads: dict[int, str], *, git: GitCollector,
110
+ ) -> tuple[dict[str, Any], dict[str, Any] | None, list[str]]:
111
+ proof: dict[str, Any] = {"status": "unproven"}
112
+ targets = {stage: result.captures["after"][1] for stage, result in stages.items() if result.captures}
113
+ if before is None or before.get("status") != "complete" or before.get("completeInventory") is not True or not before.get("head"):
114
+ return proof, None, ["A complete original task baseline is required for cumulative source comparison"]
115
+ if not stages or set(targets) != set(selected_heads) or any(
116
+ target is None or target.get("status") != "complete" or target.get("completeInventory") is not True or not target.get("head")
117
+ for target in targets.values()
118
+ ):
119
+ return proof, None, ["Selected stages do not all have complete preserved targets"]
120
+ if any(target["head"] != selected_heads[stage] for stage, target in targets.items()):
121
+ return proof, None, ["Preserved target HEAD differs from the selected completed stage head"]
122
+ heads = list(dict.fromkeys(target["head"] for target in targets.values()))
123
+ ancestors: dict[tuple[str, str], bool | None] = {}
124
+
125
+ def is_ancestor(ancestor: str, descendant: str) -> bool | None:
126
+ pair = (ancestor, descendant)
127
+ if pair not in ancestors:
128
+ ancestors[pair] = recorded_commit_is_ancestor(root, ancestor, descendant, git=git)
129
+ return ancestors[pair]
130
+
131
+ candidate = heads[0]
132
+ for head in heads[1:]:
133
+ if is_ancestor(candidate, head) is True:
134
+ candidate = head
135
+ if any(is_ancestor(head, candidate) is not True for head in [before["head"], *heads]):
136
+ return proof, None, ["Git ancestry does not establish one target containing the task baseline and every selected stage"]
137
+ representatives = [stage for stage, target in targets.items() if target["head"] == candidate]
138
+ representative = representatives[0]
139
+ target = targets[representative]
140
+ if any(not _same_source(target, targets[stage]) for stage in representatives):
141
+ return proof, None, ["Selected targets at the same HEAD do not establish identical preserved working-tree states"]
142
+ index = _preserved_index_identity(target)
143
+ if index is None or any(_preserved_index_identity(targets[stage]) != index for stage in representatives):
144
+ return proof, None, ["Selected targets at the same HEAD do not establish identical preserved Git indexes"]
145
+ commits = {}
146
+ for stage, other in targets.items():
147
+ if other["head"] == candidate:
148
+ continue
149
+ if other["head"] not in commits:
150
+ commits[other["head"]] = read_recorded_commit_source(root, other["head"], git=git).record
151
+ if not _same_source(commits[other["head"]], other) or _preserved_index_identity(other) != (digest_bytes(b""), 0):
152
+ return proof, None, [f"Stage {stage} has uncommitted or unobserved source that Git ancestry does not include"]
153
+ proof.update(status="proven", head=candidate, representativeStage=representative, equivalentStages=representatives,
154
+ targetRef=stages[representative].data["target"].get("ref"))
155
+ return proof, target, []
156
+
157
+
158
+ def _task_baseline(
159
+ root: Path, directory: Path, owner: ComparisonOwner, manifests: list[dict[str, Any]],
160
+ fingerprints: dict[str, str | None], budget: ReadBudget,
161
+ ) -> tuple[dict[str, Any], dict[str, Any] | None]:
162
+ _artifact_bytes(root, (directory / "baseline.json").relative_to(root).as_posix(), fingerprints, budget)
163
+ response, record = _read_capture(root, directory, owner, budget=budget)
164
+ _capture_inputs(root, directory, record, fingerprints)
165
+ declared = []
166
+ for manifest in manifests:
167
+ comparison = manifest.get("implementationComparison")
168
+ scope = comparison.get("taskBaseline") if isinstance(comparison, dict) else None
169
+ if not isinstance(scope, dict):
170
+ continue
171
+ baseline = scope.get("baseline")
172
+ if scope.get("owner") != owner or scope.get("comparisonDirectory") != directory.relative_to(root).as_posix() or not isinstance(baseline, dict):
173
+ raise ComparisonError("Declared task baseline does not belong to this task")
174
+ declared.append(baseline.get("baselineRef"))
175
+ reference = response.get("baselineRef")
176
+ if reference is not None and (not declared or any(value != reference for value in declared)):
177
+ return {"status": "unavailable", "ref": None,
178
+ "limitations": ["Preserved task baseline does not match the selected runs' original task baseline references"]}, None
179
+ fields = ("status", "capturedAt", "head", "baselineCommit", "limitations", "scope", "completeInventory")
180
+ view = {**{key: record[key] for key in fields if record and key in record}, "ref": reference,
181
+ "status": response["status"], "limitations": response["limitations"]}
182
+ return view, record
183
+
184
+
185
+ def _read_stage_comparison(
186
+ root: Path, row: SelectedTaskStage, card: dict[str, Any],
187
+ fingerprints: dict[str, str | None], budget: ReadBudget, *, git: GitCollector,
188
+ ) -> tuple[Assembly | None, dict[str, Any] | None]:
189
+ manifest = None
190
+ try:
191
+ manifest_path = root / row.run_manifest
192
+ raw = _artifact_bytes(root, row.run_manifest, fingerprints, budget)
193
+ if raw is None:
194
+ raise ComparisonError("Selected stage manifest is missing")
195
+ candidate = parse_owned_snapshot(manifest_path, raw, artifact="selected stage manifest").value
196
+ stage_owner, stage_directory, report = run_comparison_scope(root, manifest_path, candidate)
197
+ if stage_owner.get("stage") != str(row.stage) or final_report_data_path(report) != final_report_data_path(root / row.report):
198
+ raise ComparisonError("Selected stage report identity changed")
199
+ manifest = candidate
200
+ stage_source = read_run_comparison_source(root, stage_owner, budget=budget, fingerprints=fingerprints)
201
+ assembled = assemble_comparison(root, stage_directory, stage_owner, stage_source, budget=budget, git=git)
202
+ _merge_fingerprints(fingerprints, assembled.fingerprints)
203
+ card.update(status=assembled.data["status"], source=assembled.data["source"],
204
+ baseline=assembled.data["baseline"], target=assembled.data["target"],
205
+ limitations=assembled.data["limitations"])
206
+ card["coverage"] = {**assembled.data["coverage"],
207
+ "unobserved": [f"stage{row.stage}:{identifier}" for identifier in assembled.data["coverage"]["unobserved"]]}
208
+ card["source"] = {**card["source"], "evidence": _evidence_rows(row.stage, card["source"].get("evidence", []))}
209
+ return assembled, manifest
210
+ except _ChangedInput:
211
+ raise
212
+ except (OSError, ValueError) as exc:
213
+ card["status"] = "partial"
214
+ card["limitations"].append(str(exc))
215
+ return None, manifest
216
+
217
+
218
+ def _cumulative_view(
219
+ root: Path, before: dict[str, Any] | None, stages: dict[int, Assembly],
220
+ selected_heads: dict[int, str], data: dict[str, Any], chosen: TaskEvidenceSelection, *, git: GitCollector,
221
+ ) -> dict[str, Any]:
222
+ coverage = _coverage_union(stages)
223
+ proof, target, limitations = _integrated_target(root, before, stages, selected_heads, git=git)
224
+ chosen["integrated"] = proof
225
+ data["integration"] = proof
226
+ data["limitations"].extend(limitations)
227
+ if target is not None:
228
+ representative = proof["representativeStage"]
229
+ data["target"] = dict(stages[representative].data["target"])
230
+ if len({row["path"] for record in (before, target) for row in record["files"]}) > MAX_PATHS:
231
+ raise ComparisonError("Whole-task cumulative coverage path limit reached")
232
+ files = _file_changes(before, target)
233
+ observations = {row["path"]: row["stageObservations"] for row in coverage["files"]}
234
+ for row in files:
235
+ row["stageObservations"] = observations.get(row["path"], [])
236
+ coverage["files"] = files
237
+ observed = {row["path"] for row in files if row["change"] in {"added", "removed", "modified"}}
238
+ coverage["unexplained"] = sorted(set(coverage["unexplained"]) & observed)
239
+ else:
240
+ data["target"]["limitations"] = limitations
241
+ change_ids = {change["id"] for change in data["changes"]}
242
+ coverage["unobserved"] = [identifier for identifier in coverage["unobserved"] if identifier in change_ids]
243
+ data["coverage"] = coverage
244
+ return proof
245
+
246
+
247
+ def assemble_task_comparison(
248
+ project_root: Path, comparison_dir: Path | None, owner: ComparisonOwner, source: ComparisonSource, *,
249
+ selection: TaskComparisonSelection, budget: ReadBudget,
250
+ ) -> Assembly:
251
+ root, directory, identity = _owner_and_directory(project_root, comparison_dir, owner)
252
+ if identity.get("kind") != "task" or selection.owner != identity:
253
+ raise ComparisonError("Whole-task comparison selection belongs to another owner")
254
+ fingerprints = dict(selection.fingerprints)
255
+ chosen: TaskEvidenceSelection = {"task": selection.selection,
256
+ "stages": {str(row.stage): None for row in selection.selected_stages}, "integrated": {"status": "unproven"}}
257
+ data: dict[str, Any] = {"schemaVersion": "1.0", "status": "partial", "source": dict(source),
258
+ "baseline": {"status": "unavailable", "ref": None, "limitations": ["Original task baseline is unavailable"]},
259
+ "target": {"status": "unavailable", "ref": None, "limitations": ["A cumulative target has not been established"]},
260
+ "changes": [], "evidence": [], "stageCards": [], "requiredStages": list(selection.required_stages), "integration": {"status": "unproven"},
261
+ "coverage": {"files": [], "unexplained": [], "unobserved": [], "excluded": []},
262
+ "limitations": list(selection.limitations)}
263
+ stages: dict[int, Assembly] = {}
264
+ manifests = []
265
+ required_inputs_inspected = False
266
+ git = GitCollector(shared_budget=budget, deadline=time.monotonic() + GIT_TIMEOUT_SECONDS)
267
+ try:
268
+ if not _validate_source(root, identity, source, fingerprints, budget):
269
+ data["status"] = "stale"
270
+ data["limitations"].append("Normalized task source does not match the saved original")
271
+ return Assembly(data, fingerprints, chosen)
272
+ _artifact_bytes(root, (directory / "baseline.json").relative_to(root).as_posix(), fingerprints, budget)
273
+ if len(selection.required_stages) > MAX_RECORDS:
274
+ data["limitations"].append("Whole-task stage card limit reached; additional stages were not assembled")
275
+ selected = {row.stage: row for row in selection.selected_stages}
276
+ for stage in selection.required_stages[:MAX_RECORDS]:
277
+ row = selected.get(stage)
278
+ card: dict[str, Any] = {"stage": stage, "status": "not-generated", "lifecycle": selection.lifecycle.get(stage, "unknown"),
279
+ "source": None, "baseline": {}, "target": {}, "reportPath": row.report if row else None,
280
+ "runManifestPath": row.run_manifest if row else None, "head": row.head if row else None,
281
+ "changeIds": [], "evidenceIds": [],
282
+ "coverage": {"files": [], "unexplained": [], "unobserved": [], "excluded": []}, "limitations": []}
283
+ data["stageCards"].append(card)
284
+ if row is None:
285
+ card["limitations"].append("Stage has not been selected as complete")
286
+ data["limitations"].append(f"Stage {stage} has not been selected as complete")
287
+ continue
288
+ assembled, manifest = _read_stage_comparison(root, row, card, fingerprints, budget, git=git)
289
+ if manifest is not None:
290
+ manifests.append(manifest)
291
+ if assembled is None:
292
+ data["limitations"].append(f"Stage {stage} could not be assembled: {card['limitations'][-1]}")
293
+ continue
294
+ stages[stage] = assembled
295
+ chosen["stages"][str(stage)] = assembled.selection
296
+ if len(data["changes"]) + len(assembled.data["changes"]) > MAX_CHANGES or len(data["evidence"]) + len(assembled.data["evidence"]) > MAX_RECORDS:
297
+ card["limitations"] = [*card["limitations"], "Stage details were omitted at the whole-task row limit"]
298
+ card["status"] = "partial"
299
+ continue
300
+ changes, evidence = _stage_rows(stage, assembled.data)
301
+ data["changes"].extend(changes)
302
+ data["evidence"].extend(evidence)
303
+ card["changeIds"] = [change["id"] for change in changes]
304
+ card["evidenceIds"] = [item["id"] for item in evidence]
305
+ data["baseline"], before = _task_baseline(root, directory, identity, manifests, fingerprints, budget)
306
+ required_inputs_inspected = True
307
+ proof = _cumulative_view(root, before, stages, {row.stage: row.head for row in selection.selected_stages},
308
+ data, chosen, git=git)
309
+ data["limitations"].extend(data["baseline"]["limitations"])
310
+ ready = (selection.required_stages and len(stages) == len(selection.required_stages)
311
+ and all(card["status"] == "ready" for card in data["stageCards"])
312
+ and before is not None and before.get("status") == "complete"
313
+ and proof["status"] == "proven" and not selection.limitations)
314
+ data["status"] = "ready" if ready else "partial"
315
+ except _ChangedInput as exc:
316
+ data["status"] = "stale"
317
+ data["limitations"].append(str(exc))
318
+ except PageBudgetExhausted as exc:
319
+ data["status"] = "partial" if required_inputs_inspected else "stale"
320
+ data["limitations"].append(f"Whole-task comparison is incomplete: {exc}")
321
+ except (OSError, ValueError) as exc:
322
+ data["limitations"].append(f"Whole-task comparison is incomplete: {exc}")
323
+ if len(json.dumps(data, ensure_ascii=True).encode()) > MAX_ASSEMBLY_BYTES:
324
+ data["changes"], data["evidence"] = [], []
325
+ data["coverage"] = {"files": [], "unexplained": [], "unobserved": [], "excluded": []}
326
+ for card in data["stageCards"]:
327
+ card.update(changeIds=[], evidenceIds=[], source=None, status="partial")
328
+ if data["status"] != "stale":
329
+ data["status"] = "partial"
330
+ data["limitations"].append("Whole-task details exceeded the serialized data byte limit")
331
+ if len(json.dumps(data, ensure_ascii=True).encode()) > MAX_ASSEMBLY_BYTES:
332
+ raise ComparisonError("Whole-task metadata exceeds its serialized byte limit")
333
+ return Assembly(data, fingerprints, chosen)