@openai/codex-security 0.6.0 → 0.8.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 (308) hide show
  1. package/README.md +76 -39
  2. package/_bundled_plugin/.mcp.json +1 -0
  3. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  4. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  5. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  6. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  9. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  11. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  12. package/_bundled_plugin/mcp/native/THIRD_PARTY_NOTICES.txt +1 -1
  13. package/_bundled_plugin/mcp/native/darwin-arm64/unix.node +0 -0
  14. package/_bundled_plugin/mcp/native/darwin-x64/unix.node +0 -0
  15. package/_bundled_plugin/mcp/native/linux-arm64-gnu/unix.node +0 -0
  16. package/_bundled_plugin/mcp/native/linux-arm64-musl/unix.node +0 -0
  17. package/_bundled_plugin/mcp/native/linux-x64-gnu/unix.node +0 -0
  18. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  19. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  20. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  21. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  22. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  23. package/_bundled_plugin/references/access-advisory.md +11 -0
  24. package/_bundled_plugin/references/core-scan.md +30 -77
  25. package/_bundled_plugin/references/final-report.md +50 -184
  26. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  27. package/_bundled_plugin/references/scan-contract.md +12 -12
  28. package/_bundled_plugin/references/scan-prologue.md +1 -1
  29. package/_bundled_plugin/references/scan-runtime.md +1 -5
  30. package/_bundled_plugin/references/threat-model.md +33 -41
  31. package/_bundled_plugin/schemas/coverage.schema.json +12 -1
  32. package/_bundled_plugin/schemas/scan-manifest.schema.json +37 -11
  33. package/_bundled_plugin/schemas/tools/deep-reducer.schema.json +38 -1
  34. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  35. package/_bundled_plugin/scripts/deep_scan_config.py +39 -39
  36. package/_bundled_plugin/scripts/deep_scan_workbench.py +146 -86
  37. package/_bundled_plugin/scripts/finalize_scan_contract.py +249 -76
  38. package/_bundled_plugin/scripts/report_projection.py +49 -17
  39. package/_bundled_plugin/scripts/review_state.py +68 -0
  40. package/_bundled_plugin/scripts/threat_model_projection.py +4 -2
  41. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  42. package/_bundled_plugin/scripts/windows_scan_local_files.py +43 -14
  43. package/_bundled_plugin/scripts/workbench/retained_coverage.py +3230 -0
  44. package/_bundled_plugin/scripts/workbench/retained_records.py +627 -0
  45. package/_bundled_plugin/scripts/workbench/saved_coverage.py +651 -8
  46. package/_bundled_plugin/scripts/workbench/saved_outputs.py +72 -0
  47. package/_bundled_plugin/scripts/workbench/saved_sources.py +730 -0
  48. package/_bundled_plugin/scripts/workbench_cli.py +3 -0
  49. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  50. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +479 -0
  51. package/_bundled_plugin/scripts/workbench_db.py +55 -171
  52. package/_bundled_plugin/scripts/workbench_feedback.py +0 -1
  53. package/_bundled_plugin/scripts/workbench_finding_workflows.py +51 -9
  54. package/_bundled_plugin/scripts/workbench_native_indexes.py +56 -44
  55. package/_bundled_plugin/scripts/workbench_saved_results.py +808 -2389
  56. package/_bundled_plugin/scripts/workbench_scan_history.py +77 -7
  57. package/_bundled_plugin/scripts/workbench_schema.py +1 -1
  58. package/_bundled_plugin/scripts/workbench_source_scopes.py +4 -1
  59. package/_bundled_plugin/scripts/workbench_target.py +142 -17
  60. package/_bundled_plugin/scripts/workbench_validation.py +9 -2
  61. package/_bundled_plugin/shared/workbench-history-repairs.json +21 -0
  62. package/_bundled_plugin/shared/workbench-migrations.json +28 -0
  63. package/_bundled_plugin/skills/assess-patch-risk/SKILL.md +3 -14
  64. package/_bundled_plugin/skills/assess-patch-risk/references/windows-validation.md +14 -0
  65. package/_bundled_plugin/skills/attack-path-analysis/SKILL.md +38 -103
  66. package/_bundled_plugin/skills/attack-path-analysis/references/attack-path-facts.md +11 -73
  67. package/_bundled_plugin/skills/attack-path-analysis/references/severity-policy.md +57 -116
  68. package/_bundled_plugin/skills/deep-security-scan/SKILL.md +28 -51
  69. package/_bundled_plugin/skills/define-security-policy/SKILL.md +9 -9
  70. package/_bundled_plugin/skills/finding-discovery/SKILL.md +26 -140
  71. package/_bundled_plugin/skills/fix-finding/SKILL.md +9 -28
  72. package/_bundled_plugin/skills/propose-security-hardening/SKILL.md +28 -218
  73. package/_bundled_plugin/skills/propose-security-hardening/references/proposal-format.md +29 -424
  74. package/_bundled_plugin/skills/publish-findings/SKILL.md +32 -24
  75. package/_bundled_plugin/skills/publish-findings/references/wiz-import.md +64 -0
  76. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +12 -12
  77. package/_bundled_plugin/skills/security-scan/SKILL.md +29 -17
  78. package/_bundled_plugin/skills/security-scan/references/desktop-scan.md +11 -17
  79. package/_bundled_plugin/skills/security-scan/references/scan-artifacts-and-ledger.md +52 -69
  80. package/_bundled_plugin/skills/threat-model/SKILL.md +16 -9
  81. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  82. package/_bundled_plugin/skills/triage-finding/SKILL.md +5 -15
  83. package/_bundled_plugin/skills/triage-finding/references/ticket-intake.md +6 -6
  84. package/_bundled_plugin/skills/validation/SKILL.md +42 -104
  85. package/_bundled_plugin/skills/validation/references/validation-guidance.md +21 -106
  86. package/_bundled_plugin/skills/verify-fix/SKILL.md +4 -2
  87. package/_bundled_plugin/skills/vulnerability-writeup/SKILL.md +21 -159
  88. package/_bundled_plugin/skills/vulnerability-writeup/references/report-format.md +18 -60
  89. package/dist/api.d.ts +5 -3
  90. package/dist/api.d.ts.map +1 -1
  91. package/dist/api.js +359 -53
  92. package/dist/api.js.map +1 -1
  93. package/dist/auth.d.ts.map +1 -1
  94. package/dist/auth.js +4 -1
  95. package/dist/auth.js.map +1 -1
  96. package/dist/cli.d.ts +2 -2
  97. package/dist/cli.d.ts.map +1 -1
  98. package/dist/cli.js +696 -430
  99. package/dist/cli.js.map +1 -1
  100. package/dist/cloud-publish.d.ts.map +1 -1
  101. package/dist/cloud-publish.js +2 -23
  102. package/dist/cloud-publish.js.map +1 -1
  103. package/dist/component-scan.d.ts +8 -2
  104. package/dist/component-scan.d.ts.map +1 -1
  105. package/dist/component-scan.js +2 -0
  106. package/dist/component-scan.js.map +1 -1
  107. package/dist/contract.d.ts +5 -2
  108. package/dist/contract.d.ts.map +1 -1
  109. package/dist/contract.js +93 -45
  110. package/dist/contract.js.map +1 -1
  111. package/dist/cost.d.ts +18 -0
  112. package/dist/cost.d.ts.map +1 -1
  113. package/dist/cost.js +107 -12
  114. package/dist/cost.js.map +1 -1
  115. package/dist/coverage-presentation.d.ts +6 -0
  116. package/dist/coverage-presentation.d.ts.map +1 -0
  117. package/dist/coverage-presentation.js +34 -0
  118. package/dist/coverage-presentation.js.map +1 -0
  119. package/dist/custom-publish.js +2 -2
  120. package/dist/custom-publish.js.map +1 -1
  121. package/dist/custom-validation-prompt.js +5 -5
  122. package/dist/custom-validation-prompt.js.map +1 -1
  123. package/dist/custom-validation.d.ts.map +1 -1
  124. package/dist/custom-validation.js +47 -19
  125. package/dist/custom-validation.js.map +1 -1
  126. package/dist/deduplication/checkpointed-review.d.ts.map +1 -1
  127. package/dist/deduplication/checkpointed-review.js +3 -1
  128. package/dist/deduplication/checkpointed-review.js.map +1 -1
  129. package/dist/deduplication/codex-review.d.ts.map +1 -1
  130. package/dist/deduplication/codex-review.js +2 -2
  131. package/dist/deduplication/codex-review.js.map +1 -1
  132. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  133. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  134. package/dist/deduplication/deduplication-prompts.js +3 -0
  135. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  136. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  137. package/dist/deduplication/records-protocol.js +21 -1
  138. package/dist/deduplication/records-protocol.js.map +1 -1
  139. package/dist/deduplication/scan.d.ts.map +1 -1
  140. package/dist/deduplication/scan.js +9 -7
  141. package/dist/deduplication/scan.js.map +1 -1
  142. package/dist/endor-findings.d.ts +4 -3
  143. package/dist/endor-findings.d.ts.map +1 -1
  144. package/dist/endor-findings.js +16 -11
  145. package/dist/endor-findings.js.map +1 -1
  146. package/dist/external-findings-import.d.ts.map +1 -1
  147. package/dist/external-findings-import.js +13 -5
  148. package/dist/external-findings-import.js.map +1 -1
  149. package/dist/external-findings-local.d.ts +1 -0
  150. package/dist/external-findings-local.d.ts.map +1 -1
  151. package/dist/external-findings-local.js +14 -3
  152. package/dist/external-findings-local.js.map +1 -1
  153. package/dist/external-findings-publish.d.ts +2 -1
  154. package/dist/external-findings-publish.d.ts.map +1 -1
  155. package/dist/external-findings-publish.js +64 -28
  156. package/dist/external-findings-publish.js.map +1 -1
  157. package/dist/external-findings-read.d.ts +12 -1
  158. package/dist/external-findings-read.d.ts.map +1 -1
  159. package/dist/external-findings-read.js +25 -6
  160. package/dist/external-findings-read.js.map +1 -1
  161. package/dist/external-findings.d.ts +2 -0
  162. package/dist/external-findings.d.ts.map +1 -1
  163. package/dist/external-findings.js.map +1 -1
  164. package/dist/external-import-contract.d.ts +7 -1
  165. package/dist/external-import-contract.d.ts.map +1 -1
  166. package/dist/external-import-contract.js +63 -31
  167. package/dist/external-import-contract.js.map +1 -1
  168. package/dist/external-imports-feature.d.ts +6 -0
  169. package/dist/external-imports-feature.d.ts.map +1 -0
  170. package/dist/external-imports-feature.js +51 -0
  171. package/dist/external-imports-feature.js.map +1 -0
  172. package/dist/finding-workflow.d.ts +24 -5
  173. package/dist/finding-workflow.d.ts.map +1 -1
  174. package/dist/finding-workflow.js +24 -9
  175. package/dist/finding-workflow.js.map +1 -1
  176. package/dist/github-advisories.d.ts.map +1 -1
  177. package/dist/github-advisories.js +3 -1
  178. package/dist/github-advisories.js.map +1 -1
  179. package/dist/github-findings.d.ts +4 -3
  180. package/dist/github-findings.d.ts.map +1 -1
  181. package/dist/github-findings.js +16 -14
  182. package/dist/github-findings.js.map +1 -1
  183. package/dist/host-protocol.d.ts +1 -1
  184. package/dist/host-protocol.d.ts.map +1 -1
  185. package/dist/host-protocol.js +2 -2
  186. package/dist/host-protocol.js.map +1 -1
  187. package/dist/hosted-remediation.d.ts.map +1 -1
  188. package/dist/hosted-remediation.js +19 -2
  189. package/dist/hosted-remediation.js.map +1 -1
  190. package/dist/hosted-scan.d.ts +1 -1
  191. package/dist/hosted-scan.d.ts.map +1 -1
  192. package/dist/hosted-scan.js +0 -6
  193. package/dist/hosted-scan.js.map +1 -1
  194. package/dist/import-scan.js +17 -17
  195. package/dist/import-scan.js.map +1 -1
  196. package/dist/index.d.ts +4 -3
  197. package/dist/index.d.ts.map +1 -1
  198. package/dist/index.js +2 -1
  199. package/dist/index.js.map +1 -1
  200. package/dist/knowledge-base.d.ts +1 -0
  201. package/dist/knowledge-base.d.ts.map +1 -1
  202. package/dist/knowledge-base.js +20 -8
  203. package/dist/knowledge-base.js.map +1 -1
  204. package/dist/mock-scan.d.ts +1 -2
  205. package/dist/mock-scan.d.ts.map +1 -1
  206. package/dist/mock-scan.js +12 -17
  207. package/dist/mock-scan.js.map +1 -1
  208. package/dist/models.d.ts +10 -1
  209. package/dist/models.d.ts.map +1 -1
  210. package/dist/models.js.map +1 -1
  211. package/dist/multiscan.d.ts.map +1 -1
  212. package/dist/multiscan.js +1 -6
  213. package/dist/multiscan.js.map +1 -1
  214. package/dist/native-json-findings.d.ts +30 -0
  215. package/dist/native-json-findings.d.ts.map +1 -0
  216. package/dist/native-json-findings.js +114 -0
  217. package/dist/native-json-findings.js.map +1 -0
  218. package/dist/opengrep-findings.d.ts +10 -0
  219. package/dist/opengrep-findings.d.ts.map +1 -0
  220. package/dist/opengrep-findings.js +198 -0
  221. package/dist/opengrep-findings.js.map +1 -0
  222. package/dist/owner-evidence.d.ts +2 -0
  223. package/dist/owner-evidence.d.ts.map +1 -1
  224. package/dist/owner-evidence.js +2 -1
  225. package/dist/owner-evidence.js.map +1 -1
  226. package/dist/patch-tui.d.ts.map +1 -1
  227. package/dist/patch-tui.js +2 -0
  228. package/dist/patch-tui.js.map +1 -1
  229. package/dist/publication.js +1 -2
  230. package/dist/publication.js.map +1 -1
  231. package/dist/publish.d.ts +2 -0
  232. package/dist/publish.d.ts.map +1 -1
  233. package/dist/publish.js +1 -1
  234. package/dist/publish.js.map +1 -1
  235. package/dist/record.d.ts +1 -0
  236. package/dist/record.d.ts.map +1 -1
  237. package/dist/record.js +10 -0
  238. package/dist/record.js.map +1 -1
  239. package/dist/remediation.d.ts +1 -25
  240. package/dist/remediation.d.ts.map +1 -1
  241. package/dist/remediation.js +3 -24
  242. package/dist/remediation.js.map +1 -1
  243. package/dist/result.d.ts +5 -3
  244. package/dist/result.d.ts.map +1 -1
  245. package/dist/result.js +9 -6
  246. package/dist/result.js.map +1 -1
  247. package/dist/runtime.d.ts.map +1 -1
  248. package/dist/runtime.js +7 -7
  249. package/dist/runtime.js.map +1 -1
  250. package/dist/scan-dashboard.d.ts +5 -3
  251. package/dist/scan-dashboard.d.ts.map +1 -1
  252. package/dist/scan-dashboard.js +79 -26
  253. package/dist/scan-dashboard.js.map +1 -1
  254. package/dist/scan-history-renderer.d.ts.map +1 -1
  255. package/dist/scan-history-renderer.js +9 -3
  256. package/dist/scan-history-renderer.js.map +1 -1
  257. package/dist/scan-owner-suggestions.d.ts +1 -1
  258. package/dist/scan-owner-suggestions.d.ts.map +1 -1
  259. package/dist/scan-owner-suggestions.js +4 -4
  260. package/dist/scan-owner-suggestions.js.map +1 -1
  261. package/dist/scan-usage-display.d.ts +8 -0
  262. package/dist/scan-usage-display.d.ts.map +1 -0
  263. package/dist/scan-usage-display.js +46 -0
  264. package/dist/scan-usage-display.js.map +1 -0
  265. package/dist/scanner-import.d.ts +1 -1
  266. package/dist/scanner-import.d.ts.map +1 -1
  267. package/dist/scanner-import.js +7 -3
  268. package/dist/scanner-import.js.map +1 -1
  269. package/dist/security-policy.d.ts.map +1 -1
  270. package/dist/security-policy.js +17 -22
  271. package/dist/security-policy.js.map +1 -1
  272. package/dist/semgrep-findings.d.ts +4 -3
  273. package/dist/semgrep-findings.d.ts.map +1 -1
  274. package/dist/semgrep-findings.js +22 -89
  275. package/dist/semgrep-findings.js.map +1 -1
  276. package/dist/skill-authentication.d.ts +18 -0
  277. package/dist/skill-authentication.d.ts.map +1 -0
  278. package/dist/skill-authentication.js +82 -0
  279. package/dist/skill-authentication.js.map +1 -0
  280. package/dist/snyk-findings.d.ts +5 -4
  281. package/dist/snyk-findings.d.ts.map +1 -1
  282. package/dist/snyk-findings.js +18 -17
  283. package/dist/snyk-findings.js.map +1 -1
  284. package/dist/suggest-owners.d.ts +4 -1
  285. package/dist/suggest-owners.d.ts.map +1 -1
  286. package/dist/suggest-owners.js +53 -21
  287. package/dist/suggest-owners.js.map +1 -1
  288. package/dist/targets.d.ts.map +1 -1
  289. package/dist/targets.js +4 -1
  290. package/dist/targets.js.map +1 -1
  291. package/dist/wiz-csv.d.ts +2 -1
  292. package/dist/wiz-csv.d.ts.map +1 -1
  293. package/dist/wiz-csv.js +3 -3
  294. package/dist/wiz-csv.js.map +1 -1
  295. package/dist/wiz-findings.d.ts +2 -1
  296. package/dist/wiz-findings.d.ts.map +1 -1
  297. package/dist/wiz-findings.js +27 -23
  298. package/dist/wiz-findings.js.map +1 -1
  299. package/docs/classify-severity-records.md +3 -4
  300. package/docs/cli.md +171 -41
  301. package/docs/dedupe-records.md +15 -1
  302. package/docs/findings-service.md +119 -118
  303. package/docs/hosted-remediation.md +19 -17
  304. package/docs/hosted-scans.md +37 -11
  305. package/package.json +9 -9
  306. package/_bundled_plugin/scripts/generate_in_scope_files.py +0 -277
  307. package/_bundled_plugin/scripts/generate_rank_input.py +0 -350
  308. package/_bundled_plugin/scripts/rank_preview.py +0 -129
@@ -0,0 +1,3230 @@
1
+ """Retain semantic scan drafts without rerunning analysis or changing run state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import hashlib
7
+ import os
8
+ from collections import Counter, deque
9
+ from functools import partial
10
+ from pathlib import Path, PurePosixPath
11
+ from typing import Any
12
+
13
+ from finalize_scan_contract import (
14
+ ContractError,
15
+ _finding_strength,
16
+ _read_json,
17
+ _recover_unsealed_findings,
18
+ _require_safe_json_value,
19
+ _validate_schema_node,
20
+ finding_candidate_id,
21
+ write_scan_local_bytes,
22
+ )
23
+ from review_state import uses_legacy_review
24
+ from workbench.retained_records import (
25
+ _append_previous_finding,
26
+ _competing_rejection_receipts,
27
+ _conflicting_outcome_receipts,
28
+ _ensure_finding_identities,
29
+ _ensure_finding_identity,
30
+ _finding_content,
31
+ _finding_identity,
32
+ _finding_key,
33
+ _identity_candidate,
34
+ _recover_preserved_worker_coverage,
35
+ _recover_preserved_worker_source,
36
+ _retained_findings,
37
+ _saved_candidate_outcomes,
38
+ _semantic_identity_key,
39
+ _worker_candidate_key,
40
+ contains_raw_value,
41
+ distinct_reports,
42
+ identifiers,
43
+ raw_owner,
44
+ raw_scope,
45
+ same_raw_content,
46
+ same_raw_finding,
47
+ same_raw_value,
48
+ )
49
+ from workbench.saved_coverage import (
50
+ _coverage_rows,
51
+ _has_candidate_metadata,
52
+ _inherit_coverage_sources,
53
+ _merge_tied_parent_observations,
54
+ _parent_observation_content,
55
+ _project_worker_closure,
56
+ _projected_worker_closure_sources,
57
+ _resolved_deferred_rows,
58
+ prepare_saved_coverage_projection,
59
+ )
60
+ from workbench.saved_sources import (
61
+ _capture_parent_observation,
62
+ _capture_saved_source,
63
+ _checkpoint_head_directory,
64
+ _checkpoint_paths,
65
+ _CheckpointSnapshotError,
66
+ _digest,
67
+ _encoded,
68
+ _freeze_source_times,
69
+ _frozen_checkpoint_heads,
70
+ _frozen_source_times,
71
+ _is_source_order_snapshot,
72
+ _latest_successful_reducer,
73
+ _model_capture,
74
+ _parent_publication_ancestors,
75
+ _read_saved_parent_result,
76
+ _read_saved_result,
77
+ _unselected_root_order,
78
+ _worker_outputs,
79
+ )
80
+ from workbench_coverage_receipts import (
81
+ _deferred_candidate_id,
82
+ _generic_surface_updates,
83
+ receipt_checkpoints,
84
+ resolve_coverage_receipts,
85
+ retain_recorded_receipt_ownership,
86
+ )
87
+ from workbench_target import committed_diff_snapshot_digest
88
+ from workbench_validation import javascript_utf8, path_within_scope
89
+
90
+
91
+ def merge_saved_results(
92
+ scan_dir: Path,
93
+ scan_id: str,
94
+ binding: dict[str, Any],
95
+ workers: list[Any],
96
+ warnings: list[str],
97
+ *,
98
+ stopped: bool,
99
+ reason: str,
100
+ scan_mode: str | None = None,
101
+ frozen_source_digests: dict[str, str] | None = None,
102
+ checkpoint_heads: dict[str, str | None] | None = None,
103
+ allow_frozen_legacy_parent: bool = False,
104
+ parent_already_captured: bool = False,
105
+ frozen_model_source: str | None = None,
106
+ selected_model_source: list[str] | None = None,
107
+ canonical_model: dict[str, Any] | None = None,
108
+ canonical_model_source: str | None = None,
109
+ canonical_sources: dict[str, str] | None = None,
110
+ finding_scope: list[tuple[str, bool]] | None = None,
111
+ preserve_canonical_parent: bool = False,
112
+ project_worker_coverage: bool = False,
113
+ created_paths: set[str] | None = None,
114
+ current_contract: bool = False,
115
+ recovery_snapshot_error: _CheckpointSnapshotError | None = None,
116
+ ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
117
+ """Read only bound parent/worker files; return an unsealed loss-preserving union."""
118
+ initial_warnings = set(warnings)
119
+ if frozen_source_digests is None:
120
+ checkpoint_heads = {}
121
+ snapshot_error = recovery_snapshot_error
122
+ captured_records = dict(snapshot_error.records) if snapshot_error is not None else {}
123
+
124
+ def capture_head(relative: str, canonical: Path | None = None) -> dict[str, tuple[str, int]]:
125
+ nonlocal snapshot_error
126
+ try:
127
+ if canonical is not None:
128
+ return _capture_parent_observation(
129
+ scan_dir,
130
+ scan_id,
131
+ canonical.name,
132
+ max(parent_modified, canonical.lstat().st_mtime_ns),
133
+ allow_frozen_legacy_parent,
134
+ created_paths=created_paths,
135
+ )
136
+ return _capture_saved_source(
137
+ scan_dir,
138
+ relative,
139
+ scan_id,
140
+ checkpoint_heads=checkpoint_heads,
141
+ created_paths=created_paths,
142
+ )
143
+ except _CheckpointSnapshotError as exc:
144
+ if "status" not in binding:
145
+ # A running coordinator can continue from its remaining evidence.
146
+ if checkpoint_heads is not None:
147
+ checkpoint_heads.pop(Path(relative).parent.as_posix(), None)
148
+ raise
149
+ # Finish selection from captured bytes before freezing an I/O failure.
150
+ snapshot_error = snapshot_error or exc
151
+ captured_records.update(exc.records)
152
+ return exc.captured
153
+
154
+ parent_context = dict(recovery_snapshot_error.parent_context) if recovery_snapshot_error else {}
155
+ try:
156
+ source_times = _frozen_source_times(
157
+ scan_dir, scan_id, frozen_source_digests or {}, parent_context
158
+ )
159
+ if snapshot_error is not None:
160
+ source_times.update({path: item[1] for path, item in snapshot_error.captured.items()})
161
+ except (ContractError, OSError, ValueError) as exc:
162
+ raise ContractError("Frozen stopped-scan checkpoint set is incomplete.") from exc
163
+ parent: dict[str, Any] | None = None
164
+ frozen_parent_path: str | None = None
165
+ parent_manifest: dict[str, Any] | None = None
166
+ parent_is_canonical = False
167
+ parent_modified = 0
168
+ parent_model_source: str | None = None
169
+ canonical_model_order: tuple[int, int] | None = None
170
+ canonical_model_digest: str | None = None
171
+ if frozen_source_digests is None or (
172
+ allow_frozen_legacy_parent and not parent_already_captured
173
+ ):
174
+ try:
175
+ parent_manifest, parent = _read_saved_parent_result(scan_dir, scan_id)
176
+ # Without an accepted head, a file-authored draft is a full replacement.
177
+ parent_file = (
178
+ "coverage.json"
179
+ if uses_legacy_review(parent_manifest["scan"])
180
+ else "scan-manifest.json"
181
+ )
182
+ parent_modified = (scan_dir / parent_file).lstat().st_mtime_ns
183
+ parent_is_canonical = True
184
+ except (ContractError, OSError, ValueError) as exc:
185
+ if not stopped:
186
+ raise
187
+ if (scan_dir / "scan-manifest.json").exists():
188
+ warnings.append(f"Could not read the saved parent draft: {exc}")
189
+ parent_manifest = None
190
+ parent = None
191
+ if parent_manifest is not None and parent is not None and not preserve_canonical_parent:
192
+ parent_scan = parent_manifest["scan"]
193
+ try:
194
+ _, _, head_modified = _read_saved_result(scan_dir, "checkpoint-head.json", scan_id)
195
+ except (ContractError, OSError, ValueError):
196
+ head_modified = None
197
+ if head_modified is not None:
198
+ # A partial tool publication must not outrank its accepted head.
199
+ parent_modified = min(
200
+ (scan_dir / name).lstat().st_mtime_ns
201
+ for name in (
202
+ "findings.json",
203
+ "scan-manifest.json",
204
+ *(["coverage.json"] if uses_legacy_review(parent_scan) else []),
205
+ )
206
+ )
207
+ if not parent_scan.get("sealedAt") or allow_frozen_legacy_parent:
208
+ payload = _encoded(parent)
209
+ parent_digest = hashlib.sha256(payload).hexdigest()
210
+ parent_checkpoint = f"checkpoints/{parent_digest}.json"
211
+ if isinstance(parent.get("threatModel"), dict):
212
+ canonical_model_source = parent_checkpoint
213
+ parent_model_source = parent_checkpoint
214
+ canonical_model_order = (0, parent_modified)
215
+ canonical_model_digest = parent_digest
216
+ parent_context["canonical"] = parent_checkpoint
217
+ parent_context["canonicalObservedAtNs"] = str(parent_modified)
218
+ checkpoint_path = scan_dir / parent_checkpoint
219
+ if not checkpoint_path.exists():
220
+ if created_paths is not None and not os.path.lexists(checkpoint_path):
221
+ created_paths.add(parent_checkpoint)
222
+ write_scan_local_bytes(scan_dir, parent_checkpoint, payload)
223
+ # A recovery copy must not appear newer than the review it copies.
224
+ os.utime(checkpoint_path, ns=(parent_modified, parent_modified))
225
+ captured = capture_head(
226
+ "checkpoint-head.json", checkpoint_path if head_modified is None else None
227
+ )
228
+ if captured and (head_modified is not None or allow_frozen_legacy_parent):
229
+ if checkpoint_heads is not None:
230
+ checkpoint_heads["."] = next(iter(captured))
231
+ parent_context["head"] = next(iter(captured))
232
+ if frozen_source_digests is not None:
233
+ frozen_source_digests = {
234
+ **frozen_source_digests,
235
+ parent_checkpoint: parent_digest,
236
+ **{path: value[0] for path, value in captured.items()},
237
+ }
238
+
239
+ sources: list[tuple[str, dict[str, Any], str | None]] = []
240
+ parent_preserved_sources: dict[str, str] = {}
241
+ source_digests: dict[str, str] = {}
242
+ source_order: dict[str, tuple[int, int]] = {}
243
+ worker_attempts: dict[str, tuple[str, int]] = {}
244
+ saved_heads: dict[str, str] = {}
245
+ saved_inputs: dict[str, str] = {}
246
+ if parent_manifest:
247
+ recorded = parent_manifest["scan"].get("preservedSources", {})
248
+ if isinstance(recorded, dict):
249
+ parent_preserved_sources = recorded
250
+ source_digests.update(parent_preserved_sources)
251
+ if frozen_source_digests is None:
252
+ source_times.update(_frozen_source_times(scan_dir, scan_id, recorded))
253
+ paths: dict[str, str | None] = {}
254
+ reducer_paths: set[str] = set()
255
+ current_results: set[str] = set()
256
+ reducer_outputs: list[tuple[Any, str, list[str], int]] = []
257
+ reducer = _latest_successful_reducer(workers)
258
+ latest_reducer: str | None = None
259
+ if reducer is not None:
260
+ try:
261
+ latest_reducer = Path(reducer["result_manifest_path"]).relative_to(scan_dir).as_posix()
262
+ paths[latest_reducer] = None
263
+ reducer_paths.add(latest_reducer)
264
+ except ValueError:
265
+ warnings.append("Skipped a reducer result outside the scan directory.")
266
+
267
+ def checkpoints(directory: str, worker_id: str | None, attempt: int = 0) -> None:
268
+ if worker_id is not None:
269
+ root = Path(directory).parent.as_posix()
270
+ worker_attempts[root] = (worker_id, attempt)
271
+ paths[f"{root}/checkpoint-head.json"] = worker_id
272
+ head_snapshots = (Path(directory).parent / "checkpoint-heads").as_posix()
273
+ for saved_directory in (directory, head_snapshots):
274
+ paths.update(dict.fromkeys(_checkpoint_paths(scan_dir, saved_directory), worker_id))
275
+
276
+ if not preserve_canonical_parent:
277
+ paths["checkpoint-head.json"] = None
278
+ checkpoints("checkpoints", None)
279
+ for worker in workers:
280
+ try:
281
+ outputs = _worker_outputs(scan_dir, worker)
282
+ except (TypeError, ValueError):
283
+ warnings.append("Skipped a worker checkpoint outside the scan directory.")
284
+ continue
285
+ if worker["kind"] == "dedup":
286
+ for directory, attempt in outputs:
287
+ checkpoint_paths = _checkpoint_paths(scan_dir, f"{directory}/checkpoints")
288
+ if not checkpoint_paths:
289
+ continue
290
+ result_path = f"{directory}/result.json"
291
+ retained_paths = [result_path, *checkpoint_paths]
292
+ paths.update(dict.fromkeys(retained_paths))
293
+ reducer_paths.update(retained_paths)
294
+ reducer_outputs.append((worker, result_path, checkpoint_paths, attempt))
295
+ continue
296
+ if worker["kind"] != "discovery":
297
+ continue
298
+ output, attempt = outputs[0]
299
+ paths[f"{output}/result.json"] = worker["id"]
300
+ current_results.add(f"{output}/result.json")
301
+ for archived, archived_attempt in outputs[1:]:
302
+ paths[f"{archived}/result.json"] = worker["id"]
303
+ checkpoints(f"{archived}/checkpoints", worker["id"], archived_attempt)
304
+ checkpoints(f"{output}/checkpoints", worker["id"], attempt)
305
+ if worker["result_manifest_path"]:
306
+ try:
307
+ current_path = Path(worker["result_manifest_path"]).relative_to(scan_dir).as_posix()
308
+ paths[current_path] = worker["id"]
309
+ current_results.add(current_path)
310
+ except ValueError:
311
+ warnings.append("Skipped a worker result outside the scan directory.")
312
+
313
+ if frozen_source_digests is None:
314
+ for relative, worker_id in list(paths.items()):
315
+ if Path(relative).name != "checkpoint-head.json":
316
+ continue
317
+ del paths[relative]
318
+ try:
319
+ captured = capture_head(relative)
320
+ if relative == "checkpoint-head.json" and frozen_source_digests is None:
321
+ parent_context["head"] = next(iter(captured))
322
+ paths.update({path: worker_id for path in captured})
323
+ except (ContractError, OSError, ValueError) as exc:
324
+ if (scan_dir / relative).exists() and not (
325
+ relative == "checkpoint-head.json" and parent is not None
326
+ ):
327
+ warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
328
+
329
+ if frozen_source_digests is not None:
330
+ source_digests.update(
331
+ {
332
+ path: digest
333
+ for path, digest in frozen_source_digests.items()
334
+ if _is_source_order_snapshot(path)
335
+ }
336
+ )
337
+ paths = {
338
+ relative: worker_id
339
+ for relative, worker_id in paths.items()
340
+ if relative in frozen_source_digests
341
+ }
342
+ current_results.intersection_update(frozen_source_digests)
343
+ if latest_reducer not in frozen_source_digests:
344
+ latest_reducer = None
345
+
346
+ discarded_by_source: dict[str, list[str]] = {}
347
+ pending = deque(paths.items())
348
+ while pending:
349
+ relative, worker_id = pending.popleft()
350
+ try:
351
+ draft, digest, observed = captured_records.get(relative) or _read_saved_result(
352
+ scan_dir, relative, scan_id, kind="dedup" if relative in reducer_paths else None
353
+ )
354
+ if frozen_source_digests is not None and frozen_source_digests[relative] != digest:
355
+ raise ContractError("checkpoint changed after the scan stopped")
356
+ source_digests[relative] = digest
357
+ source_times.setdefault(relative, observed)
358
+ source_order[relative] = (0, source_times[relative])
359
+ directory = Path(relative).parent
360
+ if directory.name in {"checkpoints", "checkpoint-heads"}:
361
+ directory = directory.parent
362
+ if _checkpoint_head_directory(relative) is not None:
363
+ saved_heads[relative] = draft["checkpoint"]
364
+ if isinstance(draft.get("inputCheckpoint"), str):
365
+ saved_inputs[relative] = draft["inputCheckpoint"]
366
+ continue
367
+ if (
368
+ checkpoint_heads is not None
369
+ and checkpoint_heads.get(directory.as_posix(), relative) is None
370
+ ):
371
+ continue
372
+ if preserve_canonical_parent and worker_id is not None:
373
+ discarded = _recover_preserved_worker_source(
374
+ scan_dir,
375
+ relative,
376
+ scan_id,
377
+ binding,
378
+ worker_id,
379
+ next(worker for worker in workers if worker["id"] == worker_id),
380
+ draft,
381
+ warnings,
382
+ )
383
+ if discarded:
384
+ discarded_by_source[relative] = discarded
385
+ # Recovery expects coverage, but reducer results only contain findings
386
+ # and context. Add an empty value after hashing the original result.
387
+ sources.append((relative, {"reviewState": {}, **draft}, worker_id))
388
+ if frozen_source_digests is None:
389
+ pending.extend(
390
+ receipt_checkpoints(
391
+ relative, worker_id, paths, partial(_checkpoint_paths, scan_dir)
392
+ ).items()
393
+ )
394
+ except (ContractError, OSError, ValueError) as exc:
395
+ if (scan_dir / relative).exists():
396
+ warnings.append(f"Preserved unreadable checkpoint {relative}: {exc}")
397
+ if frozen_source_digests is not None:
398
+ if frozen_source_digests.keys() - source_digests.keys():
399
+ raise ContractError("Frozen stopped-scan checkpoint set is incomplete.")
400
+
401
+ if checkpoint_heads is None:
402
+ checkpoint_heads = _frozen_checkpoint_heads(scan_dir, scan_id, source_digests)
403
+ heads_snapshotted = False
404
+ if frozen_source_digests is not None and snapshot_error is None:
405
+ # Raw heads are a temporary fallback, not permanent publication sources.
406
+ for relative in list(saved_heads):
407
+ if Path(relative).name != "checkpoint-head.json":
408
+ continue
409
+ captured = _capture_saved_source(
410
+ scan_dir,
411
+ relative,
412
+ scan_id,
413
+ expected_digest=source_digests[relative],
414
+ created_paths=created_paths,
415
+ )
416
+ for path, (digest, observed) in captured.items():
417
+ if path in source_digests and source_digests[path] != digest:
418
+ raise ContractError("checkpoint changed after the scan stopped")
419
+ source_digests[path] = digest
420
+ source_times.setdefault(path, observed)
421
+ if _checkpoint_head_directory(path) is not None:
422
+ saved_heads[path] = saved_heads[relative]
423
+ if relative in saved_inputs:
424
+ saved_inputs[path] = saved_inputs[relative]
425
+ if parent_context.get("head") == relative:
426
+ parent_context["head"] = path
427
+ source_order[path] = (0, observed)
428
+ key = Path(relative).parent.as_posix()
429
+ if checkpoint_heads.get(key) == relative:
430
+ checkpoint_heads[key] = path
431
+ saved_inputs.pop(relative, None)
432
+ del saved_heads[relative], source_digests[relative]
433
+ heads_snapshotted = True
434
+ if heads_snapshotted:
435
+ source_digests = {
436
+ path: digest
437
+ for path, digest in source_digests.items()
438
+ if not _is_source_order_snapshot(path)
439
+ }
440
+ headed_workers = {
441
+ worker_attempts[_checkpoint_head_directory(head).as_posix()][0]
442
+ for head in saved_heads
443
+ if _checkpoint_head_directory(head) != Path(".")
444
+ }
445
+ for relative, _, worker_id in sources:
446
+ if worker_id not in headed_workers:
447
+ continue
448
+ directory = Path(relative).parent
449
+ if directory.name == "checkpoints":
450
+ directory = directory.parent
451
+ _, attempt = worker_attempts.get(directory.as_posix(), (worker_id, 0))
452
+ source_order[relative] = (attempt, source_order[relative][1])
453
+ selected_observations: dict[str, tuple[int, int]] = {}
454
+ authoritative_heads: set[str] = set()
455
+ authoritative_observations: dict[str, tuple[int, int]] = {}
456
+ parent_heads: list[tuple[int, str]] = []
457
+ for head, checkpoint in saved_heads.items():
458
+ directory = _checkpoint_head_directory(head)
459
+ selected = (directory / "checkpoints" / checkpoint).as_posix()
460
+ if selected not in source_order:
461
+ raise ContractError("Checkpoint head is outside the saved source set.")
462
+ key = directory.as_posix()
463
+ if key in checkpoint_heads and checkpoint_heads[key] is None:
464
+ continue
465
+ observed = source_order[head][1]
466
+ attempt = 0 if directory == Path(".") else worker_attempts[key][1]
467
+ order = (attempt, observed)
468
+ if key not in checkpoint_heads or checkpoint_heads[key] in (head, selected):
469
+ authoritative_heads.add(selected)
470
+ if checkpoint_heads.get(key) == head:
471
+ authoritative_observations[selected] = order
472
+ if directory == Path("."):
473
+ parent_heads.append((observed, selected))
474
+ selected_observations[selected] = max(selected_observations.get(selected, order), order)
475
+ # A registered result independently retains its latest accepted observation.
476
+ # Restoring the head does not withdraw that result's publication authority.
477
+ registered_result_orders = {
478
+ path: order for path, order in selected_observations.items() if path in current_results
479
+ }
480
+ # A restored head selects one observation, not the newest time for its payload.
481
+ selected_observations.update(authoritative_observations)
482
+ source_order.update(selected_observations)
483
+ source_order.update(registered_result_orders)
484
+
485
+ # Keep frozen source digests over the original data, before discarding markers
486
+ # that never passed through the worker draft writer.
487
+ retain_recorded_receipt_ownership(
488
+ sources, _digest, binding["scope"]["includePaths"], finding_scope
489
+ )
490
+ drafts_by_path = {relative: draft for relative, draft, _ in sources}
491
+ # A frozen model capture supplies context without replacing earlier findings.
492
+ model_path = frozen_model_source or canonical_model_source
493
+ model_draft = drafts_by_path.get(model_path)
494
+ if (
495
+ model_draft is not None
496
+ and model_path not in selected_observations
497
+ and model_path != parent_context.get("canonical")
498
+ and isinstance(model := model_draft.get("threatModel"), dict)
499
+ and model_draft == _model_capture(scan_id, model)
500
+ ):
501
+ model_draft["complete"] = False
502
+ if frozen_source_digests is not None and "canonical" in parent_context:
503
+ canonical = parent_context["canonical"]
504
+ parent = drafts_by_path[canonical]
505
+ parent_model_source = canonical
506
+ parent_modified = int(
507
+ parent_context.get("canonicalObservedAtNs", source_order[canonical][1])
508
+ )
509
+ parent_is_canonical = True
510
+ if "head" in parent_context:
511
+ head = parent_context["head"]
512
+ parent_heads = [(source_order[head][1], f"checkpoints/{saved_heads[head]}")]
513
+
514
+ if parent is None and frozen_source_digests is not None and "canonical" not in parent_context:
515
+ # Older host snapshots remain evidence; only the newest is the current parent.
516
+ saved_parents = {
517
+ relative: draft
518
+ for relative, draft, _ in sources
519
+ if relative.startswith("checkpoints/")
520
+ and isinstance(draft.get("previousParentCheckpoints"), list)
521
+ }
522
+ previous_parents = {
523
+ relative
524
+ for draft in saved_parents.values()
525
+ for relative in draft["previousParentCheckpoints"]
526
+ if isinstance(relative, str)
527
+ }
528
+ for relative, draft in saved_parents.items():
529
+ if relative not in previous_parents:
530
+ frozen_parent_path, parent = relative, draft
531
+ parent_model_source = relative
532
+ parent_is_canonical = draft.get("canonicalParent") is True
533
+ break
534
+ projected_coverage = parent["reviewState"] if parent else {}
535
+ # V1 persists the review projection in the parent, without reducer sourceCoverage.
536
+
537
+ coverage_receipts = partial(resolve_coverage_receipts, scan_dir)
538
+
539
+ def canonical_coverage_record(field: str, item: dict[str, Any]) -> dict[str, Any]:
540
+ refs = item.get("receiptRefs", [])
541
+ if field != "surfaces" or not isinstance(refs, list):
542
+ return item
543
+ origin = projection_origins.get(id(item))
544
+ if origin is not None and (worker := workers_by_id.get(origin[0])) is not None:
545
+ refs = coverage_receipts(item, worker, origin[1])
546
+ result = {
547
+ **item,
548
+ "receiptRefs": [Path(ref).as_posix() if isinstance(ref, str) else ref for ref in refs],
549
+ }
550
+ if isinstance(provenance := result.get("provenance"), dict):
551
+ result["provenance"] = {
552
+ key: value for key, value in provenance.items() if key != "scanReceiptRefs"
553
+ }
554
+ return result
555
+
556
+ def retained_coverage_record(field: str, item: dict[str, Any]) -> dict[str, Any] | None:
557
+ return projection.retained_record(coverage, field, item, canonical_coverage_record)
558
+
559
+ reconciled_surface_ids: dict[tuple[str | None, str], str] = {}
560
+
561
+ def project_missing_record(
562
+ field: str,
563
+ item: dict[str, Any],
564
+ index: int,
565
+ worker: Any,
566
+ source: dict[str, Any],
567
+ *,
568
+ receipts_resolved: bool = False,
569
+ ) -> dict[str, Any]:
570
+ # Retain projectDiscoveryCoverage worker ownership.
571
+ prefix = f"{worker['id']}-attempt-{worker['attempt']}"
572
+
573
+ def accepted_positions(surface: dict[str, Any]) -> list[int]:
574
+ return [
575
+ position
576
+ for position, accepted in accepted_surfaces.get((worker["id"], surface["id"]), [])
577
+ if canonical_coverage_record("surfaces", accepted)
578
+ == canonical_coverage_record("surfaces", surface)
579
+ ]
580
+
581
+ def surface_id(surface: dict[str, Any], offset: int) -> str:
582
+ source_id = surface.get("id")
583
+ if id(source) not in accepted_coverage_sources and isinstance(source_id, str):
584
+ positions = accepted_positions(surface)
585
+ if len(positions) == 1:
586
+ offset = positions[0]
587
+ elif not positions:
588
+ return f"{prefix}-surface-{offset}-{_digest(surface)[:16]}"
589
+ return f"{prefix}-surface-{offset}"
590
+
591
+ result = copy.deepcopy(item)
592
+ provenance = result.get("provenance")
593
+ if not isinstance(provenance, dict):
594
+ provenance = {}
595
+ for key in ("workerId", "attempt", "sourceId", "candidateId"):
596
+ provenance.pop(key, None)
597
+ provenance.update(workerId=worker["id"], attempt=worker["attempt"])
598
+ result["provenance"] = provenance
599
+ source_rows = source.get(field, [])
600
+ inferred_id = (
601
+ isinstance(source_rows, list)
602
+ and index <= len(source_rows)
603
+ and id(source_rows[index - 1]) in inferred_coverage_ids
604
+ )
605
+ for key, name in (("id", "sourceId"), ("candidateId", "candidateId")):
606
+ if key == "id" and inferred_id:
607
+ continue
608
+ if key in item:
609
+ result["provenance"][name] = item[key]
610
+ if isinstance(item.get("candidateId"), str):
611
+ candidate_digest = hashlib.sha256(javascript_utf8(item["candidateId"])).hexdigest()
612
+ result["candidateId"] = f"{prefix}-candidate-{candidate_digest}"
613
+ if field == "surfaces":
614
+ original = source_rows[index - 1] if isinstance(source_rows, list) else item
615
+ result["id"] = surface_id(original, index)
616
+ if not receipts_resolved and (origin := projection_origins.get(id(original))):
617
+ result["receiptRefs"] = coverage_receipts(result, worker, origin[1])
618
+ previous = retained_coverage_record("surfaces", result)
619
+ if previous is not None and isinstance(previous.get("id"), str):
620
+ result["id"] = previous["id"]
621
+ else:
622
+ surfaces = coverage.get("surfaces", [])
623
+ if any(
624
+ isinstance(row, dict) and row.get("id") == result["id"]
625
+ for row in (surfaces if isinstance(surfaces, list) else [])
626
+ ):
627
+ result["id"] = f"{result['id']}-{_digest(result)[:16]}"
628
+ elif field == "deferred":
629
+ result["id"] = f"{prefix}-deferred-{index}"
630
+ if isinstance(item.get("surfaceIds"), list):
631
+ surface_ids: dict[str, str] = {}
632
+ surfaces = projected_coverage.get("surfaces", [])
633
+ for surface in surfaces if isinstance(surfaces, list) else []:
634
+ if not isinstance(surface, dict) or not isinstance(surface.get("id"), str):
635
+ continue
636
+ provenance = surface.get("provenance", {})
637
+ if (
638
+ isinstance(provenance, dict)
639
+ and provenance.get("workerId") == worker["id"]
640
+ and provenance.get("attempt") == worker["attempt"]
641
+ and isinstance(provenance.get("sourceId"), str)
642
+ ):
643
+ surface_ids.setdefault(provenance["sourceId"], surface["id"])
644
+ surfaces = source.get("surfaces", [])
645
+ source_surface_ids: dict[str, tuple[int, dict[str, Any]]] = {}
646
+ for offset, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
647
+ if isinstance(surface, dict) and isinstance(surface.get("id"), str):
648
+ source_surface_ids.setdefault(surface["id"], (offset, surface))
649
+ for (owner, source_id), accepted in accepted_surfaces.items():
650
+ if owner == worker["id"] and accepted:
651
+ source_surface_ids.setdefault(source_id, accepted[0])
652
+ for source_id, (offset, surface) in source_surface_ids.items():
653
+ if source_id not in item["surfaceIds"]:
654
+ continue
655
+ if (worker["id"], source_id) in reconciled_surface_ids:
656
+ surface_ids[source_id] = reconciled_surface_ids[(worker["id"], source_id)]
657
+ continue
658
+ projected_id = surface_id(surface, offset)
659
+ if id(source) in accepted_coverage_sources or accepted_positions(surface):
660
+ origin = projection_origins.get(id(surface))
661
+ projected = project_missing_record(
662
+ "surfaces", surface, offset, worker, origin[4] if origin else source
663
+ )
664
+ if origin := projection_origins.get(id(surface)):
665
+ projected["receiptRefs"] = coverage_receipts(
666
+ projected, worker, origin[1]
667
+ )
668
+ projected_id = projected["id"]
669
+ previous = retained_coverage_record("surfaces", projected)
670
+ if previous is not None and isinstance(previous.get("id"), str):
671
+ projected_id = previous["id"]
672
+ surface_ids[source_id] = projected_id
673
+ result["surfaceIds"] = [
674
+ surface_ids.get(value, value) if isinstance(value, str) else value
675
+ for value in item["surfaceIds"]
676
+ ]
677
+ return result
678
+
679
+ workers_by_id = {worker["id"]: worker for worker in workers}
680
+ latest_reducer_key = (
681
+ (reducer["completed_at"] or "", reducer["id"], int(reducer["attempt"] or 0))
682
+ if reducer is not None and latest_reducer in drafts_by_path
683
+ else None
684
+ )
685
+ if latest_reducer_key is None:
686
+ latest_reducer = None
687
+ for worker, result_path, checkpoint_paths, attempt in reducer_outputs:
688
+ result = drafts_by_path.get(result_path)
689
+ if result is None or not any(
690
+ drafts_by_path.get(checkpoint_path) == result for checkpoint_path in checkpoint_paths
691
+ ):
692
+ continue
693
+ current_results.add(result_path)
694
+ candidate_key = (worker["completed_at"] or "", worker["id"], attempt)
695
+ if latest_reducer_key is None or candidate_key > latest_reducer_key:
696
+ latest_reducer_key = candidate_key
697
+ latest_reducer = result_path
698
+
699
+ if parent_heads:
700
+ latest_observation = max(observed for observed, _ in parent_heads)
701
+ for observed, parent_path in parent_heads:
702
+ if observed != latest_observation:
703
+ continue
704
+ draft = drafts_by_path[parent_path]
705
+ modified = source_order[parent_path][1]
706
+ if parent is None or modified > parent_modified:
707
+ # Only a replacement head can replay without the canonical draft.
708
+ if parent_context.get("canonical") not in source_digests:
709
+ parent_context.pop("canonical", None)
710
+ parent_context.pop("canonicalObservedAtNs", None)
711
+ parent = draft
712
+ parent_model_source = parent_path
713
+ frozen_parent_path = (
714
+ parent_path
715
+ if isinstance(draft.get("previousParentCheckpoints"), list)
716
+ else None
717
+ )
718
+ parent_modified = modified
719
+ parent_is_canonical = draft.get("canonicalParent") is True
720
+ elif modified == parent_modified and _parent_observation_content(
721
+ draft
722
+ ) != _parent_observation_content(parent):
723
+ parent = _merge_tied_parent_observations(parent, draft)
724
+ parent_is_canonical = False
725
+ # A reducer supplies findings but cannot supersede saved parent coverage.
726
+ saved_parent = parent
727
+ parent_is_root = parent is not None
728
+ if parent is None and latest_reducer is not None:
729
+ parent = drafts_by_path[latest_reducer]
730
+ parent_model_source = latest_reducer
731
+
732
+ projected_coverage = saved_parent["reviewState"] if saved_parent else {}
733
+ reviews = projected_coverage.get("reviews")
734
+ reviewed_attempts = {
735
+ (review.get("workerId"), review.get("attempt"))
736
+ for review in (reviews if isinstance(reviews, list) else [])
737
+ if isinstance(review, dict)
738
+ and isinstance(review.get("workerId"), str)
739
+ and isinstance(review.get("attempt"), int)
740
+ }
741
+ # Reconcile raw source IDs and timestamps before projecting accepted outputs.
742
+ accepted_sources = {
743
+ relative
744
+ for relative, draft, worker_id in sources
745
+ if (worker := workers_by_id.get(worker_id)) is not None
746
+ and worker["status"] == "succeeded"
747
+ and worker["result_manifest_path"] == str(scan_dir / relative)
748
+ and draft.get("complete") is not False
749
+ }
750
+ reviewed_attempts.update(
751
+ (worker_id, workers_by_id[worker_id]["attempt"])
752
+ for relative, _, worker_id in sources
753
+ if relative in accepted_sources
754
+ )
755
+ projection = prepare_saved_coverage_projection(
756
+ sources,
757
+ parent,
758
+ source_order,
759
+ project_worker_coverage=project_worker_coverage,
760
+ preserve_canonical_parent=preserve_canonical_parent,
761
+ receipt_resolver=lambda relative, row, owner: resolve_coverage_receipts(
762
+ scan_dir, row, workers_by_id[owner], relative
763
+ ),
764
+ )
765
+ project_worker_coverage = projection.project_worker_coverage
766
+
767
+ def retain_coverage_row(output, item, owner, field, original=None, qualified=False):
768
+ retained = projection.retain_coverage_row(output, item, owner, field, original, qualified)
769
+ source = item if original is None else original
770
+ _inherit_coverage_sources(retained, [item, source], coverage_sources)
771
+ if preserve_canonical_parent and (
772
+ id(item) in canonical_rows or id(source) in canonical_rows
773
+ ):
774
+ canonical_rows.add(id(retained))
775
+ if field == "surfaces":
776
+ retained_surface_rows.add(id(source))
777
+ return retained
778
+
779
+ accepted_coverage_sources = {
780
+ id(draft["reviewState"]) for relative, draft, _ in sources if relative in accepted_sources
781
+ }
782
+ accepted_surfaces: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = {}
783
+ for relative, draft, worker_id in sources:
784
+ if relative not in accepted_sources:
785
+ continue
786
+ surfaces = draft["reviewState"].get("surfaces", [])
787
+ for index, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
788
+ if isinstance(surface, dict) and isinstance(surface.get("id"), str):
789
+ accepted_surfaces.setdefault((worker_id, surface["id"]), []).append(
790
+ (index, surface)
791
+ )
792
+
793
+ for _, draft, _ in sources:
794
+ questions = draft["reviewState"].get("openQuestions")
795
+ if isinstance(questions, list):
796
+ draft["reviewState"]["openQuestions"] = [
797
+ {"question": item.strip()} if isinstance(item, str) else item for item in questions
798
+ ]
799
+ projection_origins = {
800
+ id(item): (worker_id, relative, field, index, draft["reviewState"])
801
+ for relative, draft, worker_id in sources
802
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions")
803
+ for index, item in enumerate(
804
+ draft["reviewState"].get(field, [])
805
+ if isinstance(draft["reviewState"].get(field, []), list)
806
+ else [],
807
+ 1,
808
+ )
809
+ if isinstance(item, dict)
810
+ }
811
+
812
+ def project_record(
813
+ field: str,
814
+ item: dict[str, Any],
815
+ source_item: dict[str, Any] | None = None,
816
+ *,
817
+ receipts_resolved: bool = False,
818
+ ) -> dict[str, Any]:
819
+ original = item if source_item is None else source_item
820
+ origin = projection_origins.get(id(original))
821
+ if origin is None:
822
+ return item
823
+ worker_id, relative, _, index, source = origin
824
+ if relative not in accepted_sources:
825
+ directory = Path(relative).parent
826
+ if directory.name == "checkpoints":
827
+ directory = directory.parent
828
+ worker = workers_by_id.get(worker_id)
829
+ if worker is None or worker_attempts.get(directory.as_posix(), (None, None)) != (
830
+ worker_id,
831
+ worker["attempt"],
832
+ ):
833
+ return item
834
+ # Reproduced outputs and links from omitted checkpoints use the
835
+ # accepted worker's surface namespace.
836
+ accepted = next(
837
+ (
838
+ (path, draft["reviewState"])
839
+ for path, draft, owner in sources
840
+ if owner == worker_id and path in accepted_sources
841
+ ),
842
+ None,
843
+ )
844
+ if accepted is not None and source == accepted[1]:
845
+ relative, source = accepted
846
+ elif relative not in selected_observations or accepted is None:
847
+ if field == "deferred" and accepted is not None and "surfaceIds" in item:
848
+ return {
849
+ **item,
850
+ "surfaceIds": project_missing_record(
851
+ field, item, index, worker, accepted[1]
852
+ )["surfaceIds"],
853
+ }
854
+ return item
855
+ worker = workers_by_id[worker_id]
856
+ result = project_missing_record(
857
+ field, item, index, worker, source, receipts_resolved=receipts_resolved
858
+ )
859
+ if field == "surfaces" and not receipts_resolved:
860
+ result["receiptRefs"] = coverage_receipts(result, worker, relative)
861
+ return result
862
+
863
+ all_sources = ([("parent", parent, None)] if parent else []) + sources
864
+ source_owners = {relative: owner for relative, _, owner in all_sources}
865
+ inferred_coverage_ids: set[int] = set()
866
+ # Older checkpoints can omit IDs already assigned in their published output.
867
+ for field in ("deferred", "surfaces"):
868
+ named_rows: dict[str | None, list[dict[str, Any]]] = {}
869
+ for _, draft, owner in all_sources:
870
+ named_rows.setdefault(owner, []).extend(
871
+ row
872
+ for row in _coverage_rows(draft["reviewState"], field)
873
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
874
+ )
875
+ for _, draft, owner in all_sources:
876
+ rows = _coverage_rows(draft["reviewState"], field)
877
+ reserved = {
878
+ row["id"]
879
+ for row in rows
880
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
881
+ }
882
+ for row in rows:
883
+ if not isinstance(row, dict) or "id" in row:
884
+ continue
885
+ if field == "deferred" and _has_candidate_metadata(row):
886
+ continue
887
+ content = {"receiptRefs": [], **row} if field == "surfaces" else row
888
+ identity = next(
889
+ (
890
+ named["id"]
891
+ for named in named_rows[owner]
892
+ if named["id"] not in reserved
893
+ and {
894
+ **({"receiptRefs": []} if field == "surfaces" else {}),
895
+ **{key: value for key, value in named.items() if key != "id"},
896
+ }
897
+ == content
898
+ ),
899
+ None,
900
+ )
901
+ if identity is not None:
902
+ inferred_coverage_ids.add(id(row))
903
+ row["id"] = identity
904
+ reserved.add(identity)
905
+
906
+ # A discarded local surface must not fall back to another source's reused ID.
907
+ surface_ids_by_source: dict[tuple[str, str], list[str]] = {
908
+ (relative, row["id"]): []
909
+ for relative, draft, _ in all_sources
910
+ for row in (
911
+ draft["reviewState"].get("surfaces", [])
912
+ if isinstance(draft["reviewState"].get("surfaces"), list)
913
+ else []
914
+ )
915
+ if isinstance(row, dict) and isinstance(row.get("id"), str)
916
+ }
917
+ discarded_coverage_sources: set[str] = set()
918
+ if preserve_canonical_parent:
919
+ for relative, draft, worker_id in sources:
920
+ if worker_id is None:
921
+ continue
922
+ if _recover_preserved_worker_coverage(
923
+ scan_dir,
924
+ relative,
925
+ worker_id,
926
+ draft,
927
+ discarded_by_source.get(relative, []),
928
+ warnings,
929
+ ):
930
+ discarded_coverage_sources.add(relative)
931
+
932
+ if parent is None and not sources:
933
+ return None
934
+ if (
935
+ parent_manifest
936
+ and parent_manifest["scan"].get("sealedAt")
937
+ and parent_manifest["scan"].get("status") == binding["status"]
938
+ and parent_manifest["scan"].get("preservedSources") == source_digests
939
+ and parent_manifest["scan"].get("preservedCheckpointHeads", {}) == checkpoint_heads
940
+ and all(warning in initial_warnings for warning in warnings)
941
+ ):
942
+ return None
943
+
944
+ target_kind = binding["allowedTargetKinds"][0]
945
+ if (
946
+ target_kind == "git_worktree"
947
+ and "snapshotDigest" not in binding["target"]
948
+ and "git_revision" in binding["allowedTargetKinds"]
949
+ ):
950
+ target_kind = "git_revision"
951
+ target = {"kind": target_kind, **binding["target"]}
952
+ if target["kind"] == "git_diff" and "snapshotDigest" not in target:
953
+ diff_kind = {"commit": "commit", "branch_diff": "range"}[binding["coverageMode"]]
954
+ target["snapshotDigest"] = committed_diff_snapshot_digest(
955
+ diff_kind, target["baseRevision"], target["headRevision"]
956
+ )
957
+ manifest = (
958
+ copy.deepcopy(parent_manifest)
959
+ if parent_manifest
960
+ else {"scan": {"target": target, "scope": binding["scope"]}}
961
+ )
962
+ if allow_frozen_legacy_parent:
963
+ manifest["scan"]["target"] = target
964
+ for key in ("sealedAt", "artifacts", "coverageRef"):
965
+ manifest["scan"].pop(key, None)
966
+ manifest["scan"]["preservedSources"] = source_digests
967
+ manifest["scan"]["preservedCheckpointHeads"] = checkpoint_heads
968
+ # Completion follows the selected parent, including legacy terminal drafts
969
+ # that omit the optional marker, rather than an older canonical manifest.
970
+ if parent is not None:
971
+ manifest["scan"].pop("complete", None)
972
+ if "complete" in parent:
973
+ manifest["scan"]["complete"] = parent["complete"]
974
+ if isinstance(parent.get("scope"), dict):
975
+ manifest["scan"]["scope"] = copy.deepcopy(parent["scope"])
976
+ if isinstance(manifest["scan"].get("scope"), dict):
977
+ manifest["scan"]["scope"].update(copy.deepcopy(binding["scope"]))
978
+ model_checks: dict[str, dict[str, Any] | None] = {}
979
+
980
+ def recovered_model(
981
+ relative: str, draft: dict[str, Any], owner: str | None
982
+ ) -> dict[str, Any] | None:
983
+ if relative not in model_checks:
984
+ model = copy.deepcopy(draft.get("threatModel"))
985
+ if isinstance(model, dict) and owner is not None:
986
+ model["origin"] = "recovered"
987
+ schema = _read_json(
988
+ Path(__file__).resolve().parents[2] / "schemas/scan-manifest.schema.json"
989
+ )
990
+ try:
991
+ _require_safe_json_value(model, f"Saved threat model {relative}")
992
+ _validate_schema_node(
993
+ model,
994
+ schema["properties"]["scan"]["properties"]["threatModel"],
995
+ f"Saved threat model {relative}",
996
+ schema,
997
+ )
998
+ except ContractError as exc:
999
+ warnings.append(f"Skipped malformed saved threat model {relative}: {exc}")
1000
+ model = None
1001
+ model_checks[relative] = model
1002
+ return model_checks[relative]
1003
+
1004
+ parent_model = (
1005
+ recovered_model(parent_model_source or "parent", parent, None)
1006
+ if parent is not None and "threatModel" in parent
1007
+ else None
1008
+ )
1009
+ canonical_model = manifest["scan"].pop("threatModel", canonical_model)
1010
+ if parent_model is not None:
1011
+ manifest["scan"]["threatModel"] = parent_model
1012
+ if (
1013
+ selected_model_source is not None
1014
+ and parent_model_source in drafts_by_path
1015
+ and (
1016
+ parent_model_source != canonical_model_source
1017
+ or canonical_model_digest is None
1018
+ or source_digests[parent_model_source] == canonical_model_digest
1019
+ )
1020
+ ):
1021
+ selected_model_source[:] = [parent_model_source]
1022
+ elif frozen_model_source is None:
1023
+ # Model fallback is independent of whether older findings are superseded.
1024
+ if canonical_model is not None:
1025
+ canonical_model = recovered_model("canonical", {"threatModel": canonical_model}, None)
1026
+ if (
1027
+ canonical_model_source is not None
1028
+ and Path(canonical_model_source).parent != Path("checkpoints")
1029
+ ) or (
1030
+ canonical_model_source is None
1031
+ and isinstance(canonical_model, dict)
1032
+ and canonical_model.get("origin") == "recovered"
1033
+ ):
1034
+ # Worker models follow their own selected head and independent result.
1035
+ canonical_model = None
1036
+ canonical_model_source = None
1037
+ if (
1038
+ canonical_model_source in drafts_by_path
1039
+ and recovered_model(
1040
+ canonical_model_source, drafts_by_path[canonical_model_source], None
1041
+ )
1042
+ is not None
1043
+ and (
1044
+ canonical_model_digest is None
1045
+ or source_digests[canonical_model_source] == canonical_model_digest
1046
+ )
1047
+ ):
1048
+ canonical_model = drafts_by_path[canonical_model_source].get("threatModel")
1049
+ canonical_model_order = max(
1050
+ canonical_model_order or source_order[canonical_model_source],
1051
+ source_order[canonical_model_source],
1052
+ )
1053
+ else:
1054
+ # A skipped checkpoint cannot supply provenance for valid canonical data.
1055
+ canonical_model_source = None
1056
+ root_models = [
1057
+ path
1058
+ for path in drafts_by_path
1059
+ if path in selected_observations
1060
+ and Path(path).parent == Path("checkpoints")
1061
+ and isinstance(drafts_by_path[path].get("threatModel"), dict)
1062
+ and recovered_model(path, drafts_by_path[path], None) is not None
1063
+ ]
1064
+ selected_root_models = [path for path in root_models if path in authoritative_heads]
1065
+ if isinstance(canonical_model, dict) and canonical_model_order is None:
1066
+ # Legacy publications have no model-source identity. Only newly admitted
1067
+ # observations can supersede that fallback without an explicit selection.
1068
+ new_models = {
1069
+ f"checkpoints/{checkpoint}"
1070
+ for head, checkpoint in saved_heads.items()
1071
+ if _checkpoint_head_directory(head) == Path(".")
1072
+ and head not in (canonical_sources or {})
1073
+ }
1074
+ root_models = [path for path in root_models if path in new_models]
1075
+ model_source = max(
1076
+ selected_root_models or root_models,
1077
+ key=lambda path: source_order[path],
1078
+ default=None,
1079
+ )
1080
+ if model_source is not None and (
1081
+ selected_root_models
1082
+ or not isinstance(canonical_model, dict)
1083
+ or canonical_model_order is None
1084
+ or source_order[model_source] > canonical_model_order
1085
+ ):
1086
+ manifest["scan"]["threatModel"] = copy.deepcopy(
1087
+ drafts_by_path[model_source]["threatModel"]
1088
+ )
1089
+ if selected_model_source is not None:
1090
+ selected_model_source[:] = [model_source]
1091
+ elif isinstance(canonical_model, dict):
1092
+ manifest["scan"]["threatModel"] = copy.deepcopy(canonical_model)
1093
+ if stopped and frozen_source_digests is None and canonical_model_source is None:
1094
+ # An unreadable canonical checkpoint must not leave a valid
1095
+ # inherited model dependent on live files after the first stop.
1096
+ model_draft = _model_capture(scan_id, canonical_model)
1097
+ digest = _digest(model_draft)
1098
+ canonical_model_source = f"checkpoints/{digest}.json"
1099
+ observed = (canonical_model_order or (0, parent_modified))[1]
1100
+ source_digests[canonical_model_source] = digest
1101
+ source_times[canonical_model_source] = observed
1102
+ try:
1103
+ if not (scan_dir / canonical_model_source).exists():
1104
+ if created_paths is not None and not os.path.lexists(
1105
+ scan_dir / canonical_model_source
1106
+ ):
1107
+ created_paths.add(canonical_model_source)
1108
+ write_scan_local_bytes(
1109
+ scan_dir, canonical_model_source, _encoded(model_draft)
1110
+ )
1111
+ os.utime(scan_dir / canonical_model_source, ns=(observed, observed))
1112
+ _, actual, _ = _read_saved_result(scan_dir, canonical_model_source, scan_id)
1113
+ if actual != digest:
1114
+ raise ContractError("Saved inherited model checkpoint changed.")
1115
+ except (ContractError, OSError) as exc:
1116
+ snapshot_error = snapshot_error or exc
1117
+ if selected_model_source is not None and canonical_model_source is not None:
1118
+ selected_model_source[:] = [canonical_model_source]
1119
+
1120
+ if frozen_model_source is not None:
1121
+ # Publication retries retain a valid choice from the frozen source set.
1122
+ model = drafts_by_path.get(frozen_model_source, {}).get("threatModel")
1123
+ if not isinstance(model, dict):
1124
+ raise ContractError("Frozen stopped-scan model source is unavailable.")
1125
+ model = recovered_model(
1126
+ frozen_model_source, drafts_by_path[frozen_model_source], paths[frozen_model_source]
1127
+ )
1128
+ if model is not None:
1129
+ manifest["scan"]["threatModel"] = model
1130
+ if selected_model_source is not None:
1131
+ selected_model_source[:] = [] if model is None else [frozen_model_source]
1132
+ coverage = (
1133
+ copy.deepcopy(parent["reviewState"])
1134
+ if parent and parent["reviewState"]
1135
+ else {
1136
+ "mode": binding["coverageMode"],
1137
+ "inventoryStrategy": "diff"
1138
+ if binding["coverageMode"] in {"commit", "branch_diff", "working_tree"}
1139
+ else "scoped_path"
1140
+ if binding["coverageMode"] == "scoped_path"
1141
+ else "repository",
1142
+ **binding["scope"],
1143
+ "surfaces": [],
1144
+ "explicitExclusions": [],
1145
+ "deferred": [],
1146
+ }
1147
+ )
1148
+ if isinstance(coverage.get("openQuestions"), list):
1149
+ coverage["openQuestions"] = [
1150
+ {"question": item.strip()} if isinstance(item, str) else item
1151
+ for item in coverage["openQuestions"]
1152
+ ]
1153
+ # Closure reconciliation can reuse original parent rows instead of their copies.
1154
+ canonical_rows = (
1155
+ {
1156
+ id(item)
1157
+ for parent_coverage in (
1158
+ (coverage, parent["reviewState"]) if preserve_canonical_parent else (coverage,)
1159
+ )
1160
+ for field in ("surfaces", "explicitExclusions", "deferred")
1161
+ for item in _coverage_rows(parent_coverage, field)
1162
+ }
1163
+ if parent_is_canonical
1164
+ else set()
1165
+ )
1166
+ # Links use source-local IDs until all retained surfaces receive their final IDs.
1167
+ coverage_sources: dict[int, tuple[dict[str, Any], list[str]]] = {}
1168
+ source_owners = {relative: owner for relative, _, owner in all_sources}
1169
+ retained_surface_rows: set[int] = set()
1170
+ for relative, draft, _ in all_sources:
1171
+ for field in ("surfaces", "deferred"):
1172
+ rows = draft["reviewState"].get(field)
1173
+ for row in rows if isinstance(rows, list) else []:
1174
+ if isinstance(row, dict):
1175
+ paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
1176
+ if relative not in paths_for_row:
1177
+ paths_for_row.append(relative)
1178
+ if parent:
1179
+ for field in ("surfaces", "deferred"):
1180
+ rows, originals = coverage.get(field), parent["reviewState"].get(field)
1181
+ if isinstance(rows, list) and isinstance(originals, list):
1182
+ for row, original in zip(rows, originals):
1183
+ _inherit_coverage_sources(row, [original], coverage_sources)
1184
+ if field == "surfaces":
1185
+ retained_surface_rows.update(id(original) for original in originals)
1186
+
1187
+ findings: list[dict[str, Any]] = []
1188
+ finding_positions: dict[str, tuple[int, dict[str, Any] | None]] = {}
1189
+ canonical_finding_keys: set[str] = set()
1190
+ represented: dict[str, str | None] = {}
1191
+ represented_candidates: dict[tuple[str, str, Any, Any, Any], str | None] = {}
1192
+ represented_history: dict[str, set[str]] = {}
1193
+ represented_candidate_history: dict[tuple[str, str, Any, Any, Any], set[str]] = {}
1194
+ rejected_history: dict[tuple[str, str], list[dict[str, Any]]] = {}
1195
+ stopped_parent_seal = bool(
1196
+ stopped and parent_manifest and parent_manifest["scan"].get("sealedAt")
1197
+ )
1198
+
1199
+ # A damaged canonical row must not replace a checkpoint's established identity.
1200
+ legacy_identities: dict[str, dict[str, Any] | None] = {}
1201
+ legacy_identity_sources: set[str] = set()
1202
+
1203
+ def legacy_identity_key(finding: dict[str, Any], owner: str | None) -> str:
1204
+ content = _finding_content(finding)
1205
+ locations = content.get("locations")
1206
+ if isinstance(locations, list):
1207
+ content["locations"] = sorted(
1208
+ [
1209
+ {**row, "endLine": row.get("endLine", row.get("startLine"))}
1210
+ if isinstance(row, dict)
1211
+ else row
1212
+ for row in locations
1213
+ ],
1214
+ key=_encoded,
1215
+ )
1216
+ return _digest([owner, _identity_candidate(finding), content])
1217
+
1218
+ def restore_legacy_identity(
1219
+ finding: Any, normalized: Any = None, *, allow_synthesis: bool = True
1220
+ ) -> None:
1221
+ if isinstance(finding, dict) and "identity" not in finding:
1222
+ provenance = finding.get("provenance")
1223
+ owner = provenance.get("workerId") if isinstance(provenance, dict) else None
1224
+ key = legacy_identity_key(finding, owner)
1225
+ identity = legacy_identities.get(key)
1226
+ if identity is not None:
1227
+ finding["identity"] = copy.deepcopy(identity)
1228
+ allow_synthesis = allow_synthesis or key in legacy_identity_sources
1229
+ if not allow_synthesis:
1230
+ return
1231
+ if isinstance(finding, dict) and isinstance(normalized, dict):
1232
+ finding.setdefault("identity", normalized["identity"])
1233
+ else:
1234
+ _ensure_finding_identity(finding)
1235
+
1236
+ def finding_within_scope(finding: dict[str, Any]) -> bool:
1237
+ locations = finding.get("locations", [])
1238
+ return isinstance(locations, list) and any(
1239
+ isinstance(location, dict)
1240
+ and isinstance(location.get("path"), str)
1241
+ and any(
1242
+ PurePosixPath(location["path"]) == PurePosixPath(path)
1243
+ if is_file
1244
+ else path_within_scope(location["path"], path)
1245
+ for path, is_file in (
1246
+ finding_scope
1247
+ if finding_scope is not None
1248
+ else [(path, False) for path in binding["scope"]["includePaths"]]
1249
+ )
1250
+ )
1251
+ for location in locations
1252
+ )
1253
+
1254
+ valid_findings: dict[bytes, bool] = {}
1255
+
1256
+ def valid_finding(value: Any) -> bool:
1257
+ # Use the finalizer's own per-record recovery before a draft can suppress
1258
+ # an earlier checkpoint. Invalid latest records must not hide valid history.
1259
+ document = {"scanId": scan_id, "findings": [copy.deepcopy(value)]}
1260
+ if isinstance(document["findings"][0], dict):
1261
+ restore_legacy_identity(document["findings"][0])
1262
+ key = _encoded(document["findings"][0])
1263
+ if key in valid_findings:
1264
+ return valid_findings[key]
1265
+ _recover_unsealed_findings(
1266
+ {"scan": {"id": scan_id, "target": binding["target"]}},
1267
+ document,
1268
+ Path(__file__).resolve().parents[2] / "schemas",
1269
+ scan_dir,
1270
+ [],
1271
+ current_contract=current_contract,
1272
+ )
1273
+ valid_findings[key] = bool(document["findings"])
1274
+ return valid_findings[key]
1275
+
1276
+ for _, draft, owner in all_sources:
1277
+ for value in draft["findings"]:
1278
+ if not isinstance(value, dict):
1279
+ continue
1280
+ for saved in _retained_findings(value):
1281
+ identity = saved.get("identity")
1282
+ provenance = saved.get("provenance")
1283
+ saved_owner = (
1284
+ provenance.get("workerId", owner) if isinstance(provenance, dict) else owner
1285
+ )
1286
+ key = legacy_identity_key(saved, saved_owner)
1287
+ if "identity" in saved:
1288
+ legacy_identity_sources.add(key)
1289
+ if not isinstance(identity, dict) or not valid_finding(saved):
1290
+ continue
1291
+ if key not in legacy_identities:
1292
+ legacy_identities[key] = identity
1293
+ elif legacy_identities[key] != identity:
1294
+ legacy_identities[key] = None
1295
+
1296
+ source_order["parent"] = (0, parent_modified)
1297
+
1298
+ def projection_key(field: str, item: dict[str, Any]) -> tuple[str, str]:
1299
+ # Publication may rename canonical IDs and add retained finding history.
1300
+ ignored = {"id", "previousFindings"} if field == "surfaces" else {"id"}
1301
+ content = {
1302
+ key: value
1303
+ for key, value in canonical_coverage_record(field, item).items()
1304
+ if key not in ignored
1305
+ }
1306
+ return field, _digest(content)
1307
+
1308
+ projected_sources: dict[tuple[str, str], tuple[str, dict[str, Any], tuple[int, int]]] = {}
1309
+ accepted_pending_candidates: set[tuple[str, int, str]] = set()
1310
+ selected_reported_candidates: dict[tuple[str, str], tuple[int, int]] = {}
1311
+ for relative, draft, worker_id in sources:
1312
+ if relative not in selected_observations:
1313
+ continue
1314
+ for finding in draft["findings"]:
1315
+ if isinstance(finding, dict) and valid_finding(finding):
1316
+ candidate_id = finding_candidate_id(finding)
1317
+ if candidate_id:
1318
+ key = (worker_id, candidate_id)
1319
+ selected_reported_candidates[key] = max(
1320
+ selected_reported_candidates.get(key, source_order[relative]),
1321
+ source_order[relative],
1322
+ )
1323
+ for relative, draft, worker_id in sources:
1324
+ if relative not in accepted_sources:
1325
+ continue
1326
+ worker = workers_by_id[worker_id]
1327
+ reported = {
1328
+ finding_candidate_id(finding)
1329
+ for finding in draft["findings"]
1330
+ if isinstance(finding, dict) and valid_finding(finding)
1331
+ }
1332
+ for field in ("surfaces", "deferred", "explicitExclusions"):
1333
+ rows = draft["reviewState"].get(field, [])
1334
+ for index, row in enumerate(rows if isinstance(rows, list) else [], 1):
1335
+ if not isinstance(row, dict):
1336
+ continue
1337
+ if (
1338
+ field == "deferred"
1339
+ and isinstance(candidate_id := row.get("candidateId"), str)
1340
+ and candidate_id not in reported
1341
+ and selected_reported_candidates.get((worker_id, candidate_id), (-1, -1))
1342
+ < source_order[relative]
1343
+ ):
1344
+ accepted_pending_candidates.add((worker_id, worker["attempt"], candidate_id))
1345
+ projected = project_missing_record(field, row, index, worker, draft["reviewState"])
1346
+ if field == "surfaces":
1347
+ projected["receiptRefs"] = coverage_receipts(projected, worker, relative)
1348
+ key = projection_key(field, projected)
1349
+ projected_sources[key] = (worker_id, row, source_order[relative])
1350
+
1351
+ def record_source(
1352
+ field: str, owner: str | None, item: dict[str, Any]
1353
+ ) -> tuple[str | None, dict[str, Any]]:
1354
+ # Parent-authored provenance is data, not authority over another worker.
1355
+ if (source := projected_sources.get(projection_key(field, item))) and (
1356
+ owner is None or owner == source[0]
1357
+ ):
1358
+ return source[0], source[1]
1359
+ return owner, item
1360
+
1361
+ def record_key(field: str, owner: str | None, item: dict[str, Any]) -> tuple[str | None, Any]:
1362
+ source_owner, original = record_source(field, owner, item)
1363
+ identity = original.get("id")
1364
+ return source_owner, identity if isinstance(identity, str) else None
1365
+
1366
+ def coverage_candidate(
1367
+ owner: str | None, item: dict[str, Any]
1368
+ ) -> tuple[str | None, str] | None:
1369
+ for field in ("surfaces", "deferred", "explicitExclusions"):
1370
+ source_owner, original = record_source(field, owner, item)
1371
+ if original is not item:
1372
+ owner, item = source_owner, original
1373
+ break
1374
+ else:
1375
+ # A later parent can complete a known worker proof gap, but its
1376
+ # claimed provenance cannot overturn an accepted worker finding.
1377
+ provenance = item.get("provenance")
1378
+ if owner is None and isinstance(provenance, dict):
1379
+ source_owner = provenance.get("workerId")
1380
+ attempt = provenance.get("attempt")
1381
+ candidate_id = provenance.get("candidateId")
1382
+ if (
1383
+ isinstance(source_owner, str)
1384
+ and isinstance(attempt, int)
1385
+ and isinstance(candidate_id, str)
1386
+ and (source_owner, attempt, candidate_id) in accepted_pending_candidates
1387
+ ):
1388
+ return source_owner, candidate_id
1389
+ candidate_id = (
1390
+ _deferred_candidate_id(item, owner, ambiguous_deferred)
1391
+ if any(key in item for key in ("candidate", "finding"))
1392
+ else item.get("candidateId")
1393
+ )
1394
+ return (owner, candidate_id) if isinstance(candidate_id, str) else None
1395
+
1396
+ def candidate_order(
1397
+ relative: str, owner: str | None, item: dict[str, Any] | None = None
1398
+ ) -> tuple[int, int]:
1399
+ order = source_order[relative]
1400
+ if source_owners[relative] is None and owner is not None:
1401
+ if item is not None:
1402
+ for field in ("surfaces", "deferred", "explicitExclusions"):
1403
+ key = projection_key(field, item)
1404
+ if (source := projected_sources.get(key)) and source[0] == owner:
1405
+ return source[2]
1406
+ attempt = int(workers_by_id[owner]["attempt"] or 0) if owner in headed_workers else 0
1407
+ return attempt, order[1]
1408
+ return order
1409
+
1410
+ deferred_rows = {
1411
+ relative: _coverage_rows(draft["reviewState"], "deferred")
1412
+ for relative, draft, _ in all_sources
1413
+ }
1414
+ # Accepted heads can replace equal tasks before they reach output coalescing.
1415
+ equivalent_tasks: dict[str | None, list[dict[str, Any]]] = {}
1416
+ for relative, _, owner in all_sources:
1417
+ known = equivalent_tasks.setdefault(owner, [])
1418
+ for row in deferred_rows[relative]:
1419
+ if not isinstance(row, dict):
1420
+ continue
1421
+ for previous in known:
1422
+ if previous == row:
1423
+ _inherit_coverage_sources(previous, [row], coverage_sources)
1424
+ coverage_sources[id(row)] = (row, coverage_sources[id(previous)][1])
1425
+ break
1426
+ else:
1427
+ known.append(row)
1428
+ # A legacy source can contain independent tasks with the same explicit ID.
1429
+ # Later rewrites cannot make an ID-only closure identify one of those tasks.
1430
+ ambiguous_deferred: set[tuple[str | None, str]] = set()
1431
+ for relative, _, owner in all_sources:
1432
+ by_id: dict[tuple[str | None, Any], dict[str, Any]] = {}
1433
+ candidate_aliases = {
1434
+ (source_owner, identity)
1435
+ for row in deferred_rows[relative]
1436
+ if isinstance(row, dict) and _has_candidate_metadata(row)
1437
+ for source_owner, original in [record_source("deferred", owner, row)]
1438
+ for identity in (original.get("id"), original.get("candidateId"))
1439
+ if isinstance(identity, str)
1440
+ }
1441
+ for row in deferred_rows[relative]:
1442
+ if not isinstance(row, dict) or not isinstance(identity := row.get("id"), str):
1443
+ continue
1444
+ if _has_candidate_metadata(row):
1445
+ continue
1446
+ key = record_key("deferred", owner, row)
1447
+ if key in candidate_aliases or (key in by_id and row != by_id[key]):
1448
+ ambiguous_deferred.add(key)
1449
+ by_id[key] = row
1450
+ current_drafts = ([("parent", parent, None)] if parent else []) + [
1451
+ source for source in sources if source[0] in current_results | selected_observations.keys()
1452
+ ]
1453
+
1454
+ pending_surface_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
1455
+ for relative, draft, owner in all_sources:
1456
+ surfaces = draft["reviewState"].get("surfaces", [])
1457
+ for surface in surfaces if isinstance(surfaces, list) else []:
1458
+ if (
1459
+ isinstance(surface, dict)
1460
+ and surface.get("disposition") == "needs_follow_up"
1461
+ and (candidate := coverage_candidate(owner, surface)) is not None
1462
+ ):
1463
+ order = candidate_order(relative, candidate[0], surface)
1464
+ pending_surface_orders[candidate] = max(
1465
+ pending_surface_orders.get(candidate, order), order
1466
+ )
1467
+ # Generic closures belong to one logical scan or worker, just like candidates.
1468
+ # Keep them when recovering a terminal checkpoint without its canonical write.
1469
+ closed_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
1470
+
1471
+ candidate_ids: set[tuple[str | None, str]] = set()
1472
+ accepted_deferred_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
1473
+ active_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]] = {}
1474
+ coverage_schema = _read_json(
1475
+ Path(__file__).resolve().parents[2] / "schemas" / "coverage.schema.json"
1476
+ )["properties"]
1477
+
1478
+ projected_closure_sources = _projected_worker_closure_sources(
1479
+ sources, source_order, worker_attempts, coverage_schema["resolvedDeferred"]
1480
+ )
1481
+
1482
+ for relative, draft, owner in all_sources:
1483
+ for item in deferred_rows[relative]:
1484
+ if not isinstance(item, dict):
1485
+ continue
1486
+ source_owner, original = record_source("deferred", owner, item)
1487
+ order = candidate_order(relative, source_owner, item)
1488
+ if isinstance(item.get("candidateId"), str) or "candidate" in item or "finding" in item:
1489
+ candidate_ids.update(
1490
+ (source_owner, identity)
1491
+ for identity in (original.get("id"), original.get("candidateId"))
1492
+ if isinstance(identity, str)
1493
+ )
1494
+ identity = original.get("id") or original.get("candidateId")
1495
+ if isinstance(identity, str):
1496
+ key = (source_owner, identity)
1497
+ previous = active_deferred.get(key)
1498
+ if previous is None or order > previous[0]:
1499
+ active_deferred[key] = (order, original, relative)
1500
+ if (
1501
+ relative == "parent"
1502
+ or relative in current_results
1503
+ or relative in selected_observations
1504
+ ):
1505
+ try:
1506
+ # A malformed update cannot discard valid saved evidence.
1507
+ _validate_schema_node(
1508
+ {"id": identity, **item},
1509
+ coverage_schema["deferred"]["items"],
1510
+ "coverage.deferred",
1511
+ )
1512
+ except ContractError:
1513
+ continue
1514
+ accepted_deferred_orders[key] = max(
1515
+ accepted_deferred_orders.get(key, order), order
1516
+ )
1517
+ for closure in _resolved_deferred_rows(draft, coverage_schema["resolvedDeferred"]):
1518
+ closure_owner, closure_relative = owner, relative
1519
+ if owner is None and (
1520
+ source := projected_closure_sources.get((closure["id"], closure["reason"]))
1521
+ ):
1522
+ # A copied parent closeout keeps its worker's identity and observation
1523
+ # time, so a later parent write cannot hide reopened worker work.
1524
+ closure_owner, closure, closure_relative = source
1525
+ key = (closure_owner, closure["id"])
1526
+ order = candidate_order(closure_relative, closure_owner)
1527
+ previous = closed_deferred.get(key)
1528
+ if previous is None or order > previous[0]:
1529
+ # The parent comes first, preserving its reason on equal timestamps.
1530
+ closed_deferred[key] = (order, closure, closure_relative)
1531
+ reopened_rows: list[tuple[str | None, dict[str, Any]]] = []
1532
+ reopened_generic: set[tuple[str | None, str]] = set()
1533
+ for key, (order, _, _) in list(closed_deferred.items()):
1534
+ # Equal timestamps cannot distinguish closure from reopened work.
1535
+ reopened = [
1536
+ active
1537
+ for (owner, identity), active in active_deferred.items()
1538
+ if owner == key[0]
1539
+ and (identity == key[1] or active[1].get("candidateId") == key[1])
1540
+ and active[0] >= order
1541
+ ]
1542
+ if key in candidate_ids or key in ambiguous_deferred or reopened:
1543
+ del closed_deferred[key]
1544
+ for _, item, _ in reopened:
1545
+ reopened_rows.append((key[0], item))
1546
+ if key not in candidate_ids:
1547
+ reopened_generic.add(key)
1548
+ # Retain every distinct ambiguous task even when a terminal result supersedes
1549
+ # its source. Existing output ID normalization keeps each row distinct.
1550
+ for relative, _, owner in all_sources:
1551
+ for row in deferred_rows[relative]:
1552
+ if (
1553
+ isinstance(row, dict)
1554
+ and isinstance(identity := row.get("id"), str)
1555
+ and record_key("deferred", owner, row) in ambiguous_deferred
1556
+ and not _has_candidate_metadata(row)
1557
+ and (owner, row) not in reopened_rows
1558
+ ):
1559
+ reopened_rows.append((owner, row))
1560
+ retained_closures = [
1561
+ closure
1562
+ if owner is None
1563
+ else _project_worker_closure(relative, owner, closure, worker_attempts, source_order)
1564
+ for (owner, _), (_, closure, relative) in closed_deferred.items()
1565
+ ]
1566
+ coverage.pop("resolvedDeferred", None)
1567
+ if retained_closures:
1568
+ coverage["resolvedDeferred"] = copy.deepcopy(retained_closures)
1569
+ if parent:
1570
+ coverage["deferred"] = [
1571
+ row
1572
+ for row in deferred_rows["parent"]
1573
+ if not isinstance(row, dict)
1574
+ or not isinstance(row.get("id"), str)
1575
+ or (None, row["id"]) not in closed_deferred
1576
+ ]
1577
+
1578
+ ordered_candidates = {
1579
+ (owner, identity)
1580
+ for owner, row in reopened_rows
1581
+ if (identity := _deferred_candidate_id(row, owner, ambiguous_deferred)) is not None
1582
+ and (owner, identity) in candidate_ids
1583
+ }
1584
+
1585
+ outcomes, pending_candidate_orders = _saved_candidate_outcomes(
1586
+ scan_dir,
1587
+ current_drafts,
1588
+ valid_finding,
1589
+ coverage_candidate,
1590
+ candidate_order,
1591
+ workers_by_id,
1592
+ coverage_schema,
1593
+ )
1594
+ ordered_candidates.update(pending_candidate_orders)
1595
+
1596
+ def select_outcomes(unusable_receipts):
1597
+ permitted = [entry for entry in outcomes if not unusable_receipts.intersection(entry[-1])]
1598
+ resolved, ordered_outcomes = {}, {}
1599
+ candidates = ordered_candidates.union(
1600
+ (owner, candidate_id)
1601
+ for relative, owner, candidate_id, _, _, _ in permitted
1602
+ if relative in selected_observations
1603
+ )
1604
+ selected_head_candidates = {
1605
+ (Path(relative).parent, owner, candidate_id)
1606
+ for relative, owner, candidate_id, _, _, _ in permitted
1607
+ if relative in authoritative_heads
1608
+ }
1609
+ other_root_order = _unselected_root_order(saved_heads, checkpoint_heads, source_order)
1610
+ for relative, owner, candidate_id, disposition, order, _ in permitted:
1611
+ if (
1612
+ relative in selected_observations
1613
+ and relative not in authoritative_heads
1614
+ and relative not in current_results
1615
+ and (Path(relative).parent, owner, candidate_id) in selected_head_candidates
1616
+ ):
1617
+ continue
1618
+ key = (owner, candidate_id)
1619
+ if pending_surface_orders.get(key, (-1, -1)) >= order:
1620
+ continue
1621
+ if key not in candidates:
1622
+ if relative == "parent" or relative in current_results:
1623
+ resolved.setdefault(key, disposition)
1624
+ continue
1625
+ root_terminal = (
1626
+ owner is None
1627
+ and (relative == "parent" or relative in authoritative_heads)
1628
+ and (parent if relative == "parent" else drafts_by_path[relative]).get("complete")
1629
+ is not False
1630
+ and other_root_order < order
1631
+ )
1632
+ pending_order = pending_candidate_orders.get(key, (-1, -1))
1633
+ if (pending_order > order or (pending_order == order and not root_terminal)) or any(
1634
+ (
1635
+ coverage_candidate(saved_owner, row)
1636
+ or (saved_owner, _deferred_candidate_id(row, saved_owner, ambiguous_deferred))
1637
+ )
1638
+ == key
1639
+ and (
1640
+ saved_order > order
1641
+ or saved_order == order
1642
+ and (
1643
+ not root_terminal
1644
+ or accepted_deferred_orders.get((saved_owner, identity)) == saved_order
1645
+ )
1646
+ )
1647
+ for (saved_owner, identity), (saved_order, row, _) in active_deferred.items()
1648
+ ):
1649
+ continue
1650
+ previous = ordered_outcomes.get(key)
1651
+ if (
1652
+ previous is None
1653
+ or order > previous[0]
1654
+ or (
1655
+ order == previous[0]
1656
+ and previous[1] != relative
1657
+ and previous[1] in current_results
1658
+ and (
1659
+ relative in checkpoint_heads.values()
1660
+ or relative in authoritative_observations
1661
+ )
1662
+ )
1663
+ ):
1664
+ resolved[key] = disposition
1665
+ ordered_outcomes[key] = (order, relative)
1666
+ return resolved, ordered_outcomes
1667
+
1668
+ resolved, ordered_outcomes = select_outcomes(set())
1669
+ # Only the current parent may claim that another worker finding was absorbed.
1670
+ # A superseded checkpoint must not suppress a newer independent result.
1671
+ if parent:
1672
+ for finding in parent["findings"]:
1673
+ if valid_finding(finding):
1674
+ canonical = copy.deepcopy(finding)
1675
+ restore_legacy_identity(canonical)
1676
+ canonical_key = _finding_key(canonical)
1677
+ for retained in _retained_findings(finding):
1678
+ retained_key = _finding_key(retained)
1679
+ if retained is not finding:
1680
+ represented_history.setdefault(retained_key, set()).add(
1681
+ _digest(_finding_content(retained))
1682
+ )
1683
+ previous_key = represented.get(retained_key)
1684
+ if retained_key not in represented:
1685
+ represented[retained_key] = canonical_key
1686
+ elif previous_key != canonical_key:
1687
+ # Ambiguous history cannot suppress an independent source.
1688
+ represented[retained_key] = None
1689
+ originals = finding["provenance"].get("sourceFindings", [])
1690
+ for original in originals if isinstance(originals, list) else []:
1691
+ if isinstance(original, dict) and isinstance(original.get("finding"), dict):
1692
+ source_id = original.get("id")
1693
+ candidate_id = finding_candidate_id(original["finding"])
1694
+ if isinstance(source_id, str) and ":" in source_id and candidate_id:
1695
+ candidate_key = _worker_candidate_key(
1696
+ source_id.rsplit(":", 1)[0],
1697
+ candidate_id,
1698
+ original["finding"],
1699
+ )
1700
+ previous_key = represented_candidates.get(candidate_key)
1701
+ if candidate_key not in represented_candidates:
1702
+ represented_candidates[candidate_key] = canonical_key
1703
+ elif previous_key != canonical_key:
1704
+ # Candidate ids are only authoritative within one
1705
+ # logical worker. Multiple canonical owners make
1706
+ # that worker-local identity ambiguous.
1707
+ represented_candidates[candidate_key] = None
1708
+ represented_candidate_history.setdefault(candidate_key, set()).add(
1709
+ _digest(_finding_content(original["finding"]))
1710
+ )
1711
+ selected_terminal_orders: dict[str | None, tuple[int, int]] = {}
1712
+ for relative, draft, worker_id in sources:
1713
+ if (
1714
+ relative in authoritative_heads
1715
+ and draft.get("complete") is not False
1716
+ and relative not in discarded_by_source
1717
+ and relative not in discarded_coverage_sources
1718
+ ):
1719
+ order = source_order[relative]
1720
+ selected_terminal_orders[worker_id] = max(
1721
+ selected_terminal_orders.get(worker_id, order), order
1722
+ )
1723
+ terminal_worker_orders: dict[str | None, tuple[int, int]] = {}
1724
+ terminal_coverage_orders: dict[str | None, tuple[int, int]] = {}
1725
+ for relative, draft, worker_id in sources:
1726
+ if (
1727
+ relative in current_results
1728
+ and draft.get("complete") is not False
1729
+ and relative not in discarded_by_source
1730
+ ):
1731
+ order = source_order[relative]
1732
+ terminal_worker_orders[worker_id] = max(
1733
+ terminal_worker_orders.get(worker_id, order), order
1734
+ )
1735
+ if relative not in reducer_paths and relative not in discarded_coverage_sources:
1736
+ terminal_coverage_orders[worker_id] = max(
1737
+ terminal_coverage_orders.get(worker_id, order), order
1738
+ )
1739
+ prior_terminal_orders: dict[str | None, tuple[int, int]] = {}
1740
+ partial_head_orders = {
1741
+ Path(path).parent: selected_observations[path]
1742
+ for path in authoritative_heads
1743
+ if drafts_by_path[path].get("complete") is False
1744
+ }
1745
+ for head, checkpoint in saved_heads.items():
1746
+ directory = _checkpoint_head_directory(head)
1747
+ relative = (directory / "checkpoints" / checkpoint).as_posix()
1748
+ partial_order = partial_head_orders.get(Path(relative).parent)
1749
+ if partial_order is None:
1750
+ continue
1751
+ order = (partial_order[0], source_order[head][1])
1752
+ if (
1753
+ drafts_by_path[relative].get("complete") is not False
1754
+ and relative not in discarded_by_source
1755
+ and relative not in discarded_coverage_sources
1756
+ and order <= partial_order
1757
+ ):
1758
+ # A partial head adds coverage after the preceding terminal replacement.
1759
+ worker_id = paths[relative]
1760
+ prior_terminal_orders[worker_id] = max(
1761
+ prior_terminal_orders.get(worker_id, order), order
1762
+ )
1763
+
1764
+ # Reconcile raw records before generating context-dependent publication IDs.
1765
+ logical_rows: dict[tuple[Any, ...], dict[str, dict[str, Any]]] = {}
1766
+ row_groups: dict[tuple[str, int], dict[str, Any]] = {}
1767
+ published_groups: list[dict[str, Any]] = []
1768
+
1769
+ def same_owner(left: str | None, right: str | None) -> bool:
1770
+ # Canonical recovery needs identity or recorded lineage to absorb worker evidence.
1771
+ return left == right or (not preserve_canonical_parent and (left is None or right is None))
1772
+
1773
+ def finding_source_order(source, within_worker: bool = False):
1774
+ relative, draft, _ = source
1775
+ attempt, modified = source_order[relative]
1776
+ return (
1777
+ draft.get("complete") is not False,
1778
+ attempt if within_worker else 0,
1779
+ modified,
1780
+ relative in selected_observations,
1781
+ relative in current_results,
1782
+ relative == "parent",
1783
+ )
1784
+
1785
+ terminal_findings: dict[str, list[dict[str, Any]]] = {}
1786
+ # A reducer replaces only its claimed batch, not the whole parent scan.
1787
+ parent_sources = {
1788
+ relative
1789
+ for relative, _, _ in all_sources
1790
+ if Path(relative).parent == Path("checkpoints") or (relative == "parent" and parent_is_root)
1791
+ }
1792
+ projected_paths = {
1793
+ relative
1794
+ for relative, draft, _ in all_sources
1795
+ if relative in parent_sources
1796
+ and (
1797
+ relative == "parent"
1798
+ or relative == parent_context.get("canonical")
1799
+ # The semantic tool schema forbids this host-owned projection field.
1800
+ or draft["reviewState"].get("mode") == binding["coverageMode"]
1801
+ )
1802
+ }
1803
+ projected_parents = [draft for relative, draft, _ in all_sources if relative in projected_paths]
1804
+
1805
+ def same_published_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
1806
+ if not valid_finding(left) or not valid_finding(right):
1807
+ return False
1808
+ return (
1809
+ same_raw_value(_finding_content(left), _finding_content(right))
1810
+ and (
1811
+ "identity" not in left
1812
+ or same_raw_value(_finding_identity(left), _finding_identity(right))
1813
+ )
1814
+ and same_raw_value(
1815
+ {
1816
+ key: value
1817
+ for key, value in left.get("provenance", {}).items()
1818
+ if key not in ("previousFindings", "preservedIdentity")
1819
+ },
1820
+ {
1821
+ key: value
1822
+ for key, value in right.get("provenance", {}).items()
1823
+ if key not in ("previousFindings", "preservedIdentity")
1824
+ },
1825
+ )
1826
+ )
1827
+
1828
+ def represented_by_parent(values: list[dict[str, Any]], draft: dict[str, Any]) -> bool:
1829
+ remaining = [row for row in draft["findings"] if isinstance(row, dict)]
1830
+ for value in values:
1831
+ match = next(
1832
+ (
1833
+ index
1834
+ for index, row in enumerate(remaining)
1835
+ if same_published_finding(value, row)
1836
+ ),
1837
+ None,
1838
+ )
1839
+ if match is None:
1840
+ return False
1841
+ remaining.pop(match)
1842
+ return True
1843
+
1844
+ terminal_sources: set[str] = set()
1845
+ for relative, draft, _ in all_sources:
1846
+ if (
1847
+ scan_mode == "deep"
1848
+ and not allow_frozen_legacy_parent
1849
+ and relative in parent_sources
1850
+ and draft.get("complete") is not False
1851
+ and all(valid_finding(value) for value in draft["findings"])
1852
+ ):
1853
+ terminal_sources.add(relative)
1854
+ if relative not in projected_paths:
1855
+ identified = copy.deepcopy(draft["findings"])
1856
+ _ensure_finding_identities(identified)
1857
+ terminal_findings[relative] = identified
1858
+ # Legacy projections alone do not record the submitted replacement batch.
1859
+ if not terminal_findings:
1860
+ terminal_sources.clear()
1861
+ head_path = (
1862
+ f"checkpoints/{saved_heads[parent_context['head']]}"
1863
+ if "head" in parent_context and not allow_frozen_legacy_parent
1864
+ else None
1865
+ )
1866
+ head_input = saved_inputs.get(parent_context.get("head"))
1867
+ ancestors = _parent_publication_ancestors(head_input, drafts_by_path)
1868
+ committed_parent = parent
1869
+ committed_path = "parent" if parent_is_root else None
1870
+ if head_path and (
1871
+ not parent_is_canonical or any(parent == drafts_by_path.get(path) for path in ancestors)
1872
+ ):
1873
+ committed_path = head_path
1874
+ committed_parent = drafts_by_path[head_path]
1875
+ committed_time = source_order.get(committed_path, (0, 0))[1]
1876
+ pending_terminals = set()
1877
+ superseded_terminals = set()
1878
+ unordered_terminals = set()
1879
+ for relative, values in terminal_findings.items():
1880
+ publication = drafts_by_path[relative].get("publication")
1881
+ if isinstance(publication, dict):
1882
+ previous = publication.get("previousCheckpoint")
1883
+ if Path(relative).name == head_input:
1884
+ continue
1885
+ if (
1886
+ f"checkpoints/{previous}" if previous is not None else None
1887
+ ) != head_path or publication.get("previousInputCheckpoint") != head_input:
1888
+ superseded_terminals.add(relative)
1889
+ continue
1890
+ pending_terminals.add(relative)
1891
+ elif not any(represented_by_parent(values, draft) for draft in projected_parents):
1892
+ # Legacy inputs have no causal link to an accepted publication. A
1893
+ # backdated observation cannot prove that accepted findings were removed.
1894
+ if source_order[relative][1] >= committed_time:
1895
+ pending_terminals.add(relative)
1896
+ else:
1897
+ unordered_terminals.add(relative)
1898
+ terminal_cutoffs = (
1899
+ {committed_path}
1900
+ if committed_path in terminal_sources
1901
+ else terminal_sources - superseded_terminals
1902
+ )
1903
+ terminal_parent_time = max(
1904
+ (source_order[relative][1] for relative in pending_terminals or terminal_cutoffs),
1905
+ default=None,
1906
+ )
1907
+ pending_terminals = {
1908
+ relative
1909
+ for relative in pending_terminals
1910
+ if source_order[relative][1] == terminal_parent_time
1911
+ }
1912
+ for relative in pending_terminals | unordered_terminals:
1913
+ identified = copy.deepcopy(drafts_by_path[relative]["findings"])
1914
+ _ensure_finding_identities(identified, deep=True)
1915
+ terminal_findings[relative] = identified
1916
+ current_findings = [
1917
+ previous
1918
+ for value in (committed_parent["findings"] if committed_parent else [])
1919
+ if isinstance(value, dict)
1920
+ for previous in _retained_findings(value)
1921
+ ]
1922
+ replaced_findings = [
1923
+ value
1924
+ for draft in projected_parents
1925
+ for value in draft["findings"]
1926
+ if isinstance(value, dict)
1927
+ and (
1928
+ pending_terminals
1929
+ or (
1930
+ terminal_sources
1931
+ and not any(
1932
+ same_published_finding(value, previous) for previous in current_findings
1933
+ )
1934
+ )
1935
+ )
1936
+ ]
1937
+
1938
+ def replaced_parent_finding(relative: str, owner: str | None, value: Any) -> bool:
1939
+ if (
1940
+ owner is not None
1941
+ or relative in pending_terminals | unordered_terminals
1942
+ or not isinstance(value, dict)
1943
+ ):
1944
+ return False
1945
+ return any(same_published_finding(value, previous) for previous in replaced_findings)
1946
+
1947
+ terminal_worker_attempts: dict[str, int] = {}
1948
+ if terminal_parent_time is not None:
1949
+ for relative, _, owner in all_sources:
1950
+ attempt, modified = source_order[relative]
1951
+ if owner is not None and modified <= terminal_parent_time:
1952
+ terminal_worker_attempts[owner] = max(
1953
+ terminal_worker_attempts.get(owner, attempt), attempt
1954
+ )
1955
+
1956
+ def precedes_terminal_parent(relative: str, owner: str | None) -> bool:
1957
+ attempt, modified = source_order[relative]
1958
+ return relative in superseded_terminals or (
1959
+ relative not in unordered_terminals
1960
+ and terminal_parent_time is not None
1961
+ and (
1962
+ modified < terminal_parent_time
1963
+ or attempt < terminal_worker_attempts.get(owner, attempt)
1964
+ )
1965
+ )
1966
+
1967
+ finding_sources = [
1968
+ source for source in all_sources if not precedes_terminal_parent(source[0], source[2])
1969
+ ]
1970
+ # Publication chronology spans workers; attempt numbers only order one worker's revisions.
1971
+ for source in sorted(finding_sources, key=lambda item: finding_source_order(item)[2:]):
1972
+ relative, draft, source_owner = source
1973
+ explicit_identity_counts = Counter(
1974
+ _semantic_identity_key(sibling, _finding_identity(sibling))
1975
+ for sibling in draft["findings"]
1976
+ if isinstance(sibling, dict)
1977
+ and isinstance(sibling.get("identity"), dict)
1978
+ and ((relative == "parent" and parent_is_canonical) or finding_within_scope(sibling))
1979
+ )
1980
+ pending = []
1981
+ for index, value in enumerate(draft["findings"]):
1982
+ if (
1983
+ not isinstance(value, dict)
1984
+ or replaced_parent_finding(relative, source_owner, value)
1985
+ or not valid_finding(value)
1986
+ or (
1987
+ not (relative == "parent" and parent_is_canonical)
1988
+ and not finding_within_scope(value)
1989
+ )
1990
+ ):
1991
+ continue
1992
+ owner = raw_owner(value, source_owner)
1993
+ scope = raw_scope(value)
1994
+ candidate = finding_candidate_id(value)
1995
+ scopes = [scope, (scope[0], candidate)] if candidate else [scope]
1996
+ publication_identity = (
1997
+ _finding_identity(
1998
+ value if "identity" in value else terminal_findings[relative][index]
1999
+ )
2000
+ if relative in terminal_findings
2001
+ else None
2002
+ )
2003
+ matches = [
2004
+ group
2005
+ for group in {
2006
+ key: group
2007
+ for saved_scope in scopes
2008
+ for key, group in logical_rows.get(saved_scope, {}).items()
2009
+ }.values()
2010
+ if same_owner(owner, group["owner"])
2011
+ and (
2012
+ publication_identity is None
2013
+ or group["identity"] is None
2014
+ or _semantic_identity_key(value, group["identity"])
2015
+ == _semantic_identity_key(value, publication_identity)
2016
+ )
2017
+ and (
2018
+ (relative == "parent" and parent_is_canonical)
2019
+ or group["identity"] is None
2020
+ or "identity" not in value
2021
+ or _semantic_identity_key(value, group["identity"])
2022
+ == _semantic_identity_key(value, _finding_identity(value))
2023
+ )
2024
+ and all(same_raw_finding(value, previous) for previous in group["rows"])
2025
+ ]
2026
+ ranked = []
2027
+ for group in matches:
2028
+ latest = group["latest"]
2029
+ if (
2030
+ isinstance(value.get("identity"), dict)
2031
+ and explicit_identity_counts[
2032
+ _semantic_identity_key(value, _finding_identity(value))
2033
+ ]
2034
+ == 1
2035
+ and group["identity"] is not None
2036
+ and _semantic_identity_key(value, _finding_identity(value))
2037
+ == _semantic_identity_key(value, group["identity"])
2038
+ ):
2039
+ rank = 4
2040
+ elif (
2041
+ owner == group["owner"]
2042
+ and same_raw_content(value, latest)
2043
+ and _identity_candidate(value) == _identity_candidate(latest)
2044
+ and identifiers(value) == identifiers(latest)
2045
+ ):
2046
+ rank = 3
2047
+ elif any(same_raw_content(value, previous) for previous in group["rows"]):
2048
+ rank = 2
2049
+ elif (
2050
+ latest.get("title") == value.get("title")
2051
+ and raw_scope(latest) == scope
2052
+ and all(
2053
+ previous is None or current == previous
2054
+ for current, previous in zip(
2055
+ identifiers(value), identifiers(latest), strict=True
2056
+ )
2057
+ )
2058
+ ):
2059
+ rank = 1
2060
+ else:
2061
+ rank = 0
2062
+ ranked.append((group, rank))
2063
+ pending.append((index, value, owner, scopes, ranked))
2064
+ assigned = {}
2065
+ claimed = set()
2066
+ for index, value, owner, _, matches in pending:
2067
+ for group, _ in matches:
2068
+ if (
2069
+ group["key"] not in claimed
2070
+ and owner == group["owner"]
2071
+ and same_raw_value(value, group["latest"])
2072
+ ):
2073
+ assigned[index] = group
2074
+ claimed.add(group["key"])
2075
+ break
2076
+ for rank in (4, 3, 2, 1, 0):
2077
+ identity_claims = {
2078
+ group["key"]
2079
+ for index, _, _, _, matches in pending
2080
+ for group, score in matches
2081
+ if score == 4 and assigned.get(index) is group
2082
+ }
2083
+ options = {
2084
+ index: [
2085
+ group
2086
+ for group, score in matches
2087
+ if score >= rank
2088
+ and (
2089
+ group["key"] not in claimed
2090
+ or (rank == 0 and group["key"] not in identity_claims)
2091
+ )
2092
+ ]
2093
+ for index, _, _, _, matches in pending
2094
+ if index not in assigned
2095
+ }
2096
+ counts = {}
2097
+ for groups in options.values():
2098
+ for group in groups:
2099
+ counts[group["key"]] = counts.get(group["key"], 0) + 1
2100
+ chosen = {
2101
+ index: groups[0]
2102
+ for index, groups in options.items()
2103
+ if len(groups) == 1
2104
+ and groups[0]["key"] not in claimed
2105
+ and counts[groups[0]["key"]] == 1
2106
+ }
2107
+ assigned.update(chosen)
2108
+ claimed.update(group["key"] for group in chosen.values())
2109
+ current_groups: list[tuple[int, dict[str, Any]]] = []
2110
+ for index, value, owner, scopes, _ in pending:
2111
+ match = assigned.get(index)
2112
+ if match is None:
2113
+ match = {
2114
+ "owner": owner,
2115
+ "rows": [],
2116
+ "identity": None,
2117
+ "key": f"raw:{len(row_groups)}",
2118
+ }
2119
+ for saved_scope in scopes:
2120
+ logical_rows.setdefault(saved_scope, {})[match["key"]] = match
2121
+ if match["owner"] is None:
2122
+ match["owner"] = owner
2123
+ if not any(same_raw_value(value, previous) for previous in match["rows"]):
2124
+ match["rows"].append(value)
2125
+ observations = match.setdefault("observations", {})
2126
+ previous = observations.get(source_owner)
2127
+ if previous is None or (
2128
+ finding_source_order(source, True),
2129
+ _finding_strength(value),
2130
+ ) > (
2131
+ finding_source_order(previous[0], True),
2132
+ _finding_strength(previous[1]),
2133
+ ):
2134
+ observations[source_owner] = (source, value)
2135
+ match["latest"] = max(
2136
+ observations.values(),
2137
+ key=lambda observation: (
2138
+ finding_source_order(observation[0]),
2139
+ _finding_strength(observation[1]),
2140
+ ),
2141
+ )[1]
2142
+ if relative in terminal_findings:
2143
+ match["identity"] = copy.deepcopy(
2144
+ _finding_identity(
2145
+ value if "identity" in value else terminal_findings[relative][index]
2146
+ )
2147
+ )
2148
+ elif "identity" in value and (match["identity"] is None or relative == "parent"):
2149
+ match["identity"] = copy.deepcopy(_finding_identity(value))
2150
+ row_groups[(relative, index)] = match
2151
+ current_groups.append((index, match))
2152
+ if source_owner is None:
2153
+ current_ordered = [
2154
+ group for _, group in sorted(current_groups, key=lambda item: item[0])
2155
+ ]
2156
+ ordered = current_ordered + [
2157
+ group for group in published_groups if group not in current_ordered
2158
+ ]
2159
+ normalized = []
2160
+ for group in ordered:
2161
+ value = copy.deepcopy(group["latest"])
2162
+ if group["identity"] is not None:
2163
+ value["identity"] = copy.deepcopy(group["identity"])
2164
+ normalized.append(value)
2165
+ _ensure_finding_identities(normalized)
2166
+ for group, value in zip(ordered, normalized, strict=True):
2167
+ group["identity"] = value["identity"]
2168
+ published_groups = ordered
2169
+
2170
+ # A later worker draft can collapse raw duplicates that it fully contains.
2171
+ # Keep established identities and any evidence absent from the newer report.
2172
+ contained_groups = set()
2173
+ for group in {group["key"]: group for group in row_groups.values()}.values():
2174
+ owner = group["owner"]
2175
+ previous = group["observations"].get(owner)
2176
+ if owner is None or group["identity"] is not None or previous is None:
2177
+ continue
2178
+ for current in logical_rows.get(raw_scope(group["latest"]), {}).values():
2179
+ observed = current["observations"].get(owner)
2180
+ if (
2181
+ current["owner"] == owner
2182
+ and observed is not None
2183
+ and finding_source_order(observed[0], True)
2184
+ > finding_source_order(previous[0], True)
2185
+ and all(contains_raw_value(current["latest"], row) for row in group["rows"])
2186
+ ):
2187
+ contained_groups.add(group["key"])
2188
+ break
2189
+
2190
+ # An absorbed source represents every reconciled version of that worker report.
2191
+ for groups in logical_rows.values():
2192
+ for group in groups.values():
2193
+ destinations = set()
2194
+ for value in group["rows"]:
2195
+ history_key = _finding_key(value)
2196
+ if _digest(_finding_content(value)) in represented_history.get(history_key, set()):
2197
+ destinations.add(represented.get(history_key))
2198
+ elif group["owner"] and (candidate_id := finding_candidate_id(value)):
2199
+ candidate_key = _worker_candidate_key(group["owner"], candidate_id, value)
2200
+ if _digest(_finding_content(value)) in represented_candidate_history.get(
2201
+ candidate_key, set()
2202
+ ):
2203
+ destinations.add(represented_candidates[candidate_key])
2204
+ if len(destinations) == 1 and None not in destinations:
2205
+ group["parent_key"] = destinations.pop()
2206
+
2207
+ generated_worker_findings: list[dict[str, Any]] = []
2208
+
2209
+ def source_coverage_selection(
2210
+ relative: str,
2211
+ worker_id: str | None,
2212
+ ) -> tuple[bool, set[str], bool, bool, bool]:
2213
+ worker_result_order = terminal_worker_orders.get(worker_id)
2214
+ selected_terminal_order = selected_terminal_orders.get(worker_id)
2215
+ terminal_coverage_order = max(
2216
+ (
2217
+ order
2218
+ for order in (
2219
+ terminal_coverage_orders.get(worker_id),
2220
+ selected_terminal_order,
2221
+ prior_terminal_orders.get(worker_id),
2222
+ )
2223
+ if order is not None
2224
+ ),
2225
+ default=None,
2226
+ )
2227
+ selected_coverage_superseded = (
2228
+ terminal_coverage_order is not None and source_order[relative] < terminal_coverage_order
2229
+ ) or (
2230
+ selected_terminal_order is not None
2231
+ and source_order[relative][0] == selected_terminal_order[0]
2232
+ and (
2233
+ relative in selected_observations
2234
+ and relative not in authoritative_heads
2235
+ and relative not in current_results
2236
+ or (
2237
+ relative in current_results
2238
+ and relative not in authoritative_heads
2239
+ and source_order[relative] <= selected_terminal_order
2240
+ )
2241
+ )
2242
+ )
2243
+ selected_candidates = {
2244
+ candidate_id
2245
+ for (owner, candidate_id), (_, source) in ordered_outcomes.items()
2246
+ if owner == worker_id and source == relative
2247
+ }
2248
+ superseded = (
2249
+ worker_id is None
2250
+ and saved_parent is not None
2251
+ and saved_parent.get("complete") is not False
2252
+ and relative != "parent"
2253
+ and source_order[relative] <= (0, parent_modified)
2254
+ and (not stopped_parent_seal or relative in parent_preserved_sources)
2255
+ and (
2256
+ # Explicit recovery can admit checkpoints written after this parent.
2257
+ frozen_parent_path is None
2258
+ or relative == frozen_parent_path
2259
+ or relative in saved_parent.get("previousParentCheckpoints", [])
2260
+ )
2261
+ ) or (
2262
+ worker_id is not None
2263
+ and relative not in current_results
2264
+ and worker_result_order is not None
2265
+ and (
2266
+ relative not in selected_observations
2267
+ or source_order[relative] < worker_result_order
2268
+ )
2269
+ )
2270
+ worker_coverage_order = terminal_coverage_orders.get(worker_id)
2271
+ coverage_superseded = (
2272
+ superseded
2273
+ if worker_id is None
2274
+ else (
2275
+ relative not in current_results
2276
+ and worker_coverage_order is not None
2277
+ and (
2278
+ relative not in selected_observations
2279
+ or source_order[relative] < worker_coverage_order
2280
+ )
2281
+ )
2282
+ )
2283
+ # A failed result write can leave pending work outside the accepted result.
2284
+ accepted_order = (
2285
+ (0, parent_modified)
2286
+ if worker_id is None and parent is not None
2287
+ else worker_coverage_order
2288
+ )
2289
+ retain_pending = (
2290
+ coverage_superseded
2291
+ and (worker_id in headed_workers or (worker_id is None and parent_heads))
2292
+ and accepted_order is not None
2293
+ and source_order[relative] >= accepted_order
2294
+ and any(isinstance(row, dict) for row in deferred_rows[relative])
2295
+ )
2296
+ return (
2297
+ selected_coverage_superseded,
2298
+ selected_candidates,
2299
+ superseded,
2300
+ retain_pending,
2301
+ coverage_superseded,
2302
+ )
2303
+
2304
+ def coverage_row_is_retained(
2305
+ field: str,
2306
+ item: Any,
2307
+ worker_id: str | None,
2308
+ selection: tuple[bool, set[str], bool, bool, bool],
2309
+ ) -> bool:
2310
+ (
2311
+ selected_coverage_superseded,
2312
+ selected_candidates,
2313
+ superseded,
2314
+ retain_pending,
2315
+ coverage_superseded,
2316
+ ) = selection
2317
+ # A selected terminal checkpoint replaces ordinary coverage, while
2318
+ # candidate evidence and pending tasks retain their own reconciliation.
2319
+ if (
2320
+ selected_coverage_superseded
2321
+ and field != "deferred"
2322
+ and not (isinstance(item, dict) and _has_candidate_metadata(item))
2323
+ ):
2324
+ return False
2325
+ # A selected outcome must retain its evidence even if its result write failed.
2326
+ if coverage_superseded and not (
2327
+ isinstance(item, dict)
2328
+ and (
2329
+ (field == "deferred" and retain_pending)
2330
+ or (
2331
+ isinstance(item.get("candidateId"), str)
2332
+ and item["candidateId"] in selected_candidates
2333
+ and item.get("disposition") == resolved.get((worker_id, item["candidateId"]))
2334
+ )
2335
+ )
2336
+ ):
2337
+ return False
2338
+ if (
2339
+ isinstance(item, dict)
2340
+ and isinstance(
2341
+ identity := _deferred_candidate_id(item, worker_id, ambiguous_deferred)
2342
+ if field == "deferred"
2343
+ else item.get("candidateId"),
2344
+ str,
2345
+ )
2346
+ and (coverage_candidate(worker_id, item) or (worker_id, identity)) in resolved
2347
+ and (field == "deferred" or item.get("disposition") == "needs_follow_up")
2348
+ ):
2349
+ return False
2350
+ return True
2351
+
2352
+ def source_surface_receipts(relative: str, row: dict[str, Any]) -> Any:
2353
+ worker = workers_by_id.get(source_owners.get(relative))
2354
+ return coverage_receipts(row, worker, relative) if worker else row.get("receiptRefs", [])
2355
+
2356
+ replaced_deferred = {
2357
+ id(row)
2358
+ for relative, _, owner in all_sources
2359
+ for row in deferred_rows[relative]
2360
+ if isinstance(row, dict)
2361
+ and isinstance(row.get("id"), str)
2362
+ and (key := record_key("deferred", owner, row)) not in candidate_ids
2363
+ and key not in ambiguous_deferred
2364
+ and (updated := accepted_deferred_orders.get(key)) is not None
2365
+ and updated > candidate_order(relative, key[0], row)
2366
+ }
2367
+ ambiguous_surface_ids = {
2368
+ (owner, identity)
2369
+ for owner, row in reopened_rows
2370
+ if isinstance(row.get("id"), str)
2371
+ and (owner, row["id"]) in ambiguous_deferred
2372
+ and not _has_candidate_metadata(row)
2373
+ for identity in [
2374
+ row["id"],
2375
+ *(row.get("surfaceIds", []) if isinstance(row.get("surfaceIds", []), list) else []),
2376
+ ]
2377
+ if isinstance(identity, str)
2378
+ }
2379
+ for _, draft, owner in all_sources:
2380
+ by_id: dict[str, dict[str, Any]] = {}
2381
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
2382
+ if not isinstance(surface, dict) or not isinstance(identity := surface.get("id"), str):
2383
+ continue
2384
+ if identity in by_id and surface != by_id[identity]:
2385
+ ambiguous_surface_ids.add((owner, identity))
2386
+ by_id[identity] = surface
2387
+
2388
+ def ambiguous_pending_surface(row: dict[str, Any], owner: str | None) -> bool:
2389
+ return (
2390
+ isinstance(row.get("id"), str)
2391
+ and (owner, row["id"]) in ambiguous_surface_ids
2392
+ and row.get("disposition") == "needs_follow_up"
2393
+ and not _has_candidate_metadata(row)
2394
+ )
2395
+
2396
+ def retain_findings(relative, draft, worker_id, selected_candidates, skip_superseded_findings):
2397
+ normalized_findings = copy.deepcopy(draft["findings"])
2398
+ _ensure_finding_identities(
2399
+ [finding for finding in normalized_findings if valid_finding(finding)]
2400
+ )
2401
+ for index, (value, normalized) in enumerate(
2402
+ zip(draft["findings"], normalized_findings, strict=True)
2403
+ ):
2404
+ if precedes_terminal_parent(relative, worker_id) or replaced_parent_finding(
2405
+ relative, worker_id, value
2406
+ ):
2407
+ continue
2408
+ _ensure_finding_identity(normalized)
2409
+ group = row_groups.get((relative, index))
2410
+ if group is not None and group["key"] in contained_groups:
2411
+ continue
2412
+ if skip_superseded_findings and not (
2413
+ isinstance(value, dict)
2414
+ and (candidate_id := finding_candidate_id(value)) in selected_candidates
2415
+ and resolved.get((worker_id, candidate_id)) == "reported"
2416
+ ):
2417
+ continue
2418
+ if relative == "parent" and parent_is_canonical:
2419
+ finding = copy.deepcopy(value)
2420
+ group = row_groups.get((relative, index))
2421
+ restore_legacy_identity(
2422
+ finding,
2423
+ group or normalized,
2424
+ allow_synthesis=stopped
2425
+ or (isinstance(finding, dict) and _identity_candidate(finding) is not None)
2426
+ or (group is not None and any("identity" in row for row in group["rows"])),
2427
+ )
2428
+ provenance = finding.get("provenance") if isinstance(finding, dict) else None
2429
+ owner = provenance.get("workerId") if isinstance(provenance, dict) else None
2430
+ candidate_id = finding_candidate_id(finding) if isinstance(finding, dict) else None
2431
+ if (
2432
+ stopped_parent_seal
2433
+ and isinstance(owner, str)
2434
+ and candidate_id
2435
+ and resolved.get((owner, candidate_id)) in ("rejected", "not_applicable")
2436
+ ):
2437
+ rejected_history.setdefault((owner, candidate_id), []).append(finding)
2438
+ continue
2439
+ if valid_finding(finding):
2440
+ key = _finding_key(finding)
2441
+ if group is not None:
2442
+ key = group.setdefault("merge_key", key)
2443
+ finding_positions.setdefault(key, (len(findings), group))
2444
+ if preserve_canonical_parent:
2445
+ canonical_finding_keys.add(key)
2446
+ findings.append(finding)
2447
+ continue
2448
+ if (
2449
+ relative != "parent"
2450
+ and parent
2451
+ and value in parent["findings"]
2452
+ and not precedes_terminal_parent("parent", None)
2453
+ and not replaced_parent_finding("parent", None, value)
2454
+ ):
2455
+ continue
2456
+ if not isinstance(value, dict):
2457
+ warnings.append(f"Retained malformed finding evidence in {relative}.")
2458
+ continue
2459
+ finding = copy.deepcopy(value)
2460
+ candidate_id = finding_candidate_id(finding)
2461
+ if relative != "parent" and resolved.get((worker_id, candidate_id)) in {
2462
+ "rejected",
2463
+ "not_applicable",
2464
+ }:
2465
+ if preserve_canonical_parent:
2466
+ rejected_history.setdefault((worker_id, candidate_id), []).append(finding)
2467
+ for item in _coverage_rows(coverage, "surfaces"):
2468
+ if isinstance(item, dict) and (
2469
+ coverage_candidate(None, item) == (worker_id, candidate_id)
2470
+ or (
2471
+ preserve_canonical_parent
2472
+ and item.get("candidateId") == candidate_id
2473
+ and any(
2474
+ source_owners[source] == worker_id
2475
+ for source in coverage_sources.get(id(item), (item, []))[1]
2476
+ )
2477
+ )
2478
+ or (
2479
+ not preserve_canonical_parent
2480
+ and coverage_candidate(None, item) == (None, candidate_id)
2481
+ )
2482
+ ):
2483
+ _append_previous_finding(item, finding)
2484
+ continue
2485
+ for key in ("findingId", "occurrenceId", "fingerprints"):
2486
+ finding.pop(key, None)
2487
+ if not finding_within_scope(finding):
2488
+ warnings.append(f"Skipped out-of-scope finding from {relative}.")
2489
+ continue
2490
+ provenance = finding.setdefault("provenance", {"source": "local_plugin"})
2491
+ if not isinstance(provenance, dict):
2492
+ findings.append(finding)
2493
+ continue
2494
+ if worker_id:
2495
+ provenance.setdefault("workerId", worker_id)
2496
+ group = row_groups.get((relative, index))
2497
+ if relative in terminal_findings:
2498
+ terminal = terminal_findings[relative][index]
2499
+ finding["identity"] = copy.deepcopy(terminal["identity"])
2500
+ if "preservedIdentity" in terminal.get("provenance", {}):
2501
+ provenance.setdefault(
2502
+ "preservedIdentity",
2503
+ copy.deepcopy(terminal["provenance"]["preservedIdentity"]),
2504
+ )
2505
+ elif group is not None and group["identity"] is not None:
2506
+ finding.setdefault("identity", copy.deepcopy(group["identity"]))
2507
+ if worker_id is not None and "identity" not in finding:
2508
+ generated_worker_findings.append(finding)
2509
+ finding.setdefault("identity", normalized["identity"])
2510
+ if not valid_finding(finding):
2511
+ findings.append(finding)
2512
+ continue
2513
+ # Terminal siblings remain separate even when their preserved authored
2514
+ # identities and locations coincide. Worker revisions reuse the group.
2515
+ key = (
2516
+ group["key"]
2517
+ if group is not None
2518
+ and (group["identity"] is None or relative in terminal_findings)
2519
+ else _finding_key(finding)
2520
+ )
2521
+ if group is not None:
2522
+ key = group.setdefault("merge_key", key)
2523
+ # Distinct reconciled reports may share an anchor and source location.
2524
+ if key in finding_positions and distinct_reports(group, finding_positions[key][1]):
2525
+ key = group["merge_key"] = group["key"]
2526
+ key = group.get("parent_key", key)
2527
+ represented_by_parent = False
2528
+ if relative != "parent":
2529
+ history_key = _finding_key(value)
2530
+ # A singleton key is not evidence that a new batch sibling was
2531
+ # absorbed. Only recorded content may reuse that historical edge.
2532
+ if _digest(_finding_content(value)) not in represented_history.get(
2533
+ history_key, set()
2534
+ ):
2535
+ history_key = key
2536
+ if history_key in represented:
2537
+ mapped_key = represented[history_key]
2538
+ historical_contents = represented_history.get(history_key, set())
2539
+ elif worker_id and candidate_id:
2540
+ candidate_key = _worker_candidate_key(worker_id, candidate_id, finding)
2541
+ mapped_key = represented_candidates.get(candidate_key)
2542
+ historical_contents = represented_candidate_history.get(candidate_key, set())
2543
+ else:
2544
+ mapped_key = None
2545
+ historical_contents = set()
2546
+ if mapped_key is not None:
2547
+ key = mapped_key
2548
+ represented_by_parent = _digest(_finding_content(value)) in historical_contents
2549
+ if key in finding_positions:
2550
+ position, retained_group = finding_positions[key]
2551
+ retained = findings[position]
2552
+ for field in ("anchor", "instance"):
2553
+ if field in retained["identity"]:
2554
+ finding["identity"][field] = retained["identity"][field]
2555
+ else:
2556
+ finding["identity"].pop(field, None)
2557
+ if finding != retained:
2558
+ if (
2559
+ key not in canonical_finding_keys
2560
+ and not represented_by_parent
2561
+ and (
2562
+ value is group["latest"]
2563
+ if group is not None and group is retained_group
2564
+ else _finding_strength(finding) > _finding_strength(retained)
2565
+ )
2566
+ ):
2567
+ previous = copy.deepcopy(retained)
2568
+ previous_history = previous["provenance"].pop("previousFindings", [])
2569
+ if "preservedIdentity" in retained["provenance"]:
2570
+ finding["provenance"]["preservedIdentity"] = copy.deepcopy(
2571
+ retained["provenance"]["preservedIdentity"]
2572
+ )
2573
+ retained = finding
2574
+ findings[position] = retained
2575
+ finding_positions[key] = (position, group)
2576
+ else:
2577
+ previous = copy.deepcopy(value)
2578
+ previous_history = previous.get("provenance", {}).pop(
2579
+ "previousFindings", []
2580
+ )
2581
+ retained_provenance = retained["provenance"]
2582
+ for field in ("sourceFindingIds", "sourceFindings", "originalCandidates"):
2583
+ values = retained_provenance.get(field, [])
2584
+ values = list(values) if isinstance(values, list) else []
2585
+ previous_values = previous.get("provenance", {}).get(field, [])
2586
+ for item in previous_values if isinstance(previous_values, list) else []:
2587
+ if item not in values:
2588
+ values.append(copy.deepcopy(item))
2589
+ if values:
2590
+ retained_provenance[field] = values
2591
+ retained_history = retained_provenance.get("previousFindings")
2592
+ history = (
2593
+ [item for item in retained_history if isinstance(item, dict)]
2594
+ if isinstance(retained_history, list)
2595
+ else []
2596
+ )
2597
+ for original in [
2598
+ *(previous_history if isinstance(previous_history, list) else []),
2599
+ previous,
2600
+ ]:
2601
+ if not isinstance(original, dict):
2602
+ continue
2603
+ owner = retained_provenance.get("workerId", worker_id)
2604
+ source_key = _finding_key(original, owner)
2605
+ source_content = _finding_content(original)
2606
+ already_retained = any(
2607
+ source_key == _finding_key(historical, owner)
2608
+ and source_content == _finding_content(historical)
2609
+ for historical in _retained_findings(retained)
2610
+ )
2611
+ if (
2612
+ not already_retained
2613
+ and original not in history
2614
+ and original != retained
2615
+ ):
2616
+ history.append(original)
2617
+ if history or retained_history is not None:
2618
+ retained_provenance["previousFindings"] = history
2619
+ continue
2620
+ finding_positions[key] = (len(findings), group)
2621
+ findings.append(finding)
2622
+
2623
+ competing_receipts = _competing_rejection_receipts(
2624
+ outcomes, all_sources, source_surface_receipts
2625
+ )
2626
+ check_outcome_receipts = bool(competing_receipts)
2627
+ dry_run = check_outcome_receipts
2628
+ unavailable = set()
2629
+ if dry_run:
2630
+ initial_coverage = coverage
2631
+ initial_canonical_rows = canonical_rows
2632
+ initial_sources = coverage_sources
2633
+ initial_surface_rows = retained_surface_rows
2634
+ initial_ids = surface_ids_by_source
2635
+ initial_projection = projection
2636
+ output_warnings = warnings
2637
+
2638
+ def retain_surface_links(owner, row):
2639
+ if isinstance(row, dict):
2640
+ links = row.get("surfaceIds", [])
2641
+ for identity in [row.get("id"), *(links if isinstance(links, list) else [])]:
2642
+ if isinstance(identity, str):
2643
+ pending_surface_ids.add((owner, identity))
2644
+
2645
+ def surface_is_retained(relative: str, owner: str | None, row: Any) -> bool:
2646
+ selection = source_coverage_selection(relative, owner)
2647
+ if (
2648
+ isinstance(row, dict)
2649
+ and isinstance(row.get("id"), str)
2650
+ and (owner, row["id"]) in pending_surface_ids
2651
+ ):
2652
+ selection = (False, *selection[1:])
2653
+ return coverage_row_is_retained("surfaces", row, owner, selection)
2654
+
2655
+ while True:
2656
+ if check_outcome_receipts:
2657
+ warnings = [] if dry_run else output_warnings
2658
+ coverage = copy.deepcopy(initial_coverage)
2659
+ canonical_rows = initial_canonical_rows.copy()
2660
+ coverage_sources = {
2661
+ identity: (row, paths.copy()) for identity, (row, paths) in initial_sources.items()
2662
+ }
2663
+ for field in ("surfaces", "deferred", "explicitExclusions"):
2664
+ for initial, current in zip(
2665
+ _coverage_rows(initial_coverage, field),
2666
+ _coverage_rows(coverage, field),
2667
+ strict=True,
2668
+ ):
2669
+ if id(initial) in initial_canonical_rows:
2670
+ canonical_rows.add(id(current))
2671
+ _inherit_coverage_sources(current, [initial], coverage_sources)
2672
+ retained_surface_rows = initial_surface_rows.copy()
2673
+ surface_ids_by_source = {key: ids.copy() for key, ids in initial_ids.items()}
2674
+ reconciled_surface_ids.clear()
2675
+ projection = type(initial_projection)(
2676
+ initial_projection.project_worker_coverage,
2677
+ initial_projection.legacy_surface_links,
2678
+ sources,
2679
+ )
2680
+ # Apply reconciled outcomes to coverage already copied from the parent too.
2681
+ for field in ("surfaces", "deferred"):
2682
+ rows = coverage.get(field)
2683
+ if isinstance(rows, list):
2684
+ coverage[field] = [
2685
+ row
2686
+ for row in rows
2687
+ if not (
2688
+ isinstance(row, dict)
2689
+ and (
2690
+ (
2691
+ field == "deferred"
2692
+ and record_key(field, None, row) in closed_deferred
2693
+ )
2694
+ or (
2695
+ coverage_candidate(None, row) in resolved
2696
+ and (
2697
+ field == "deferred"
2698
+ or row.get("disposition") == "needs_follow_up"
2699
+ )
2700
+ )
2701
+ )
2702
+ )
2703
+ ]
2704
+
2705
+ # Reserve receipts for supporting surfaces before repairing historical refs.
2706
+ prospective_tasks = []
2707
+ for relative, _, owner in all_sources:
2708
+ selection = source_coverage_selection(relative, owner)
2709
+ for row in deferred_rows[relative]:
2710
+ if (
2711
+ coverage_row_is_retained("deferred", row, owner, selection)
2712
+ and id(row) not in replaced_deferred
2713
+ and not (
2714
+ isinstance(row, dict)
2715
+ and isinstance(row.get("id"), str)
2716
+ and record_key("deferred", owner, row) in closed_deferred
2717
+ )
2718
+ ):
2719
+ prospective_tasks.append((owner, row))
2720
+ prospective_tasks.extend(
2721
+ (owner, row)
2722
+ for owner, row in reopened_rows
2723
+ if (owner, _deferred_candidate_id(row, owner, ambiguous_deferred)) not in resolved
2724
+ )
2725
+ pending_surface_ids = set()
2726
+
2727
+ for owner, row in prospective_tasks:
2728
+ retain_surface_links(owner, row)
2729
+ if parent and isinstance(coverage.get("deferred"), list):
2730
+ previous = parent["reviewState"].get("deferred", [])
2731
+ removed_parent = (
2732
+ [row for row in previous if id(row) in replaced_deferred]
2733
+ if isinstance(previous, list)
2734
+ else []
2735
+ )
2736
+ for row in coverage["deferred"]:
2737
+ if row not in removed_parent:
2738
+ retain_surface_links(None, row)
2739
+
2740
+ fallback_surfaces = projection.fallback_surfaces(
2741
+ coverage,
2742
+ all_sources,
2743
+ prospective_tasks,
2744
+ surface_is_retained=surface_is_retained,
2745
+ ambiguous_surface_ids=ambiguous_surface_ids,
2746
+ )
2747
+
2748
+ replaced_surfaces, surface_updates = _generic_surface_updates(
2749
+ all_sources,
2750
+ closed_deferred,
2751
+ active_deferred,
2752
+ resolved,
2753
+ reopened_generic,
2754
+ coverage_schema["surfaces"]["items"],
2755
+ deferred_rows,
2756
+ ambiguous_deferred,
2757
+ record_source,
2758
+ candidate_order,
2759
+ source_surface_receipts,
2760
+ canonical_rows=canonical_rows,
2761
+ coverage_sources=coverage_sources,
2762
+ receipt_root=scan_dir if project_worker_coverage else None,
2763
+ receipt_warnings=warnings,
2764
+ fallback_surfaces=fallback_surfaces,
2765
+ surface_is_retained=surface_is_retained,
2766
+ eligible_receipt_sources={
2767
+ relative
2768
+ for relative, draft, _ in all_sources
2769
+ if draft.get("complete") is not False or relative in selected_observations
2770
+ },
2771
+ )
2772
+ replaced_rows = {
2773
+ "surfaces": replaced_surfaces,
2774
+ "deferred": {
2775
+ id(row)
2776
+ for relative, _, owner in all_sources
2777
+ for row in deferred_rows[relative]
2778
+ if isinstance(row, dict)
2779
+ and isinstance(identity := row.get("id"), str)
2780
+ and (key := record_key("deferred", owner, row)) not in candidate_ids
2781
+ and key not in ambiguous_deferred
2782
+ and (updated := accepted_deferred_orders.get(key)) is not None
2783
+ and updated > candidate_order(relative, key[0], row)
2784
+ },
2785
+ }
2786
+ for field, replaced in replaced_rows.items():
2787
+ if parent and isinstance(coverage.get(field), list):
2788
+ previous = parent["reviewState"].get(field, [])
2789
+ if isinstance(previous, list):
2790
+ removed_parent = [row for row in previous if id(row) in replaced]
2791
+ coverage[field] = [row for row in coverage[field] if row not in removed_parent]
2792
+ if isinstance(coverage.get("surfaces"), list):
2793
+ for relative, owner, source_surface, surface in surface_updates:
2794
+ original_surface = surface
2795
+ # Generic updates already resolve each receipt at its saved source.
2796
+ surface = projection.repair_reviewed_surface(
2797
+ coverage,
2798
+ projected_coverage if parent_is_canonical else {},
2799
+ workers_by_id.get(owner),
2800
+ source_surface,
2801
+ surface,
2802
+ ) or project_record("surfaces", surface, source_surface, receipts_resolved=True)
2803
+ reconciled_surface_ids[record_key("surfaces", owner, source_surface)] = surface[
2804
+ "id"
2805
+ ]
2806
+ if surface not in coverage["surfaces"] and (
2807
+ surface is original_surface
2808
+ or retained_coverage_record("surfaces", surface) is None
2809
+ ):
2810
+ retain_coverage_row(
2811
+ coverage["surfaces"],
2812
+ surface,
2813
+ owner,
2814
+ "surfaces",
2815
+ source_surface,
2816
+ surface is not original_surface or relative == "parent",
2817
+ )
2818
+ for surface in coverage["surfaces"]:
2819
+ if isinstance(surface, dict):
2820
+ surface.setdefault("receiptRefs", [])
2821
+
2822
+ # Reopened work survives a superseded checkpoint, but current candidate
2823
+ # outcomes still apply. Parent closures cannot remove another worker's row.
2824
+ for owner, item in reopened_rows:
2825
+ source_owner, original = record_source("deferred", owner, item)
2826
+ if (
2827
+ identity := _deferred_candidate_id(original, source_owner, ambiguous_deferred)
2828
+ ) is not None and (
2829
+ source_owner,
2830
+ identity,
2831
+ ) in resolved:
2832
+ continue
2833
+ original_item = item
2834
+ item = project_record("deferred", item)
2835
+ pending = coverage.setdefault("deferred", [])
2836
+ if (
2837
+ isinstance(pending, list)
2838
+ and item not in pending
2839
+ and (item is original_item or retained_coverage_record("deferred", item) is None)
2840
+ ):
2841
+ retain_coverage_row(
2842
+ pending, item, owner, "deferred", original_item, item is not original_item
2843
+ )
2844
+ for _, draft, owner in all_sources:
2845
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
2846
+ if (
2847
+ isinstance(surface, dict)
2848
+ and ambiguous_pending_surface(surface, owner)
2849
+ and isinstance(coverage.get("surfaces"), list)
2850
+ ):
2851
+ original_surface = {**surface, "receiptRefs": surface.get("receiptRefs", [])}
2852
+ retained_surface = project_record("surfaces", original_surface, surface)
2853
+ if retained_surface not in coverage["surfaces"] and (
2854
+ retained_surface is original_surface
2855
+ or retained_coverage_record("surfaces", retained_surface) is None
2856
+ ):
2857
+ retain_coverage_row(
2858
+ coverage["surfaces"],
2859
+ retained_surface,
2860
+ owner,
2861
+ "surfaces",
2862
+ surface,
2863
+ retained_surface is not original_surface,
2864
+ )
2865
+ for relative, draft, worker_id in all_sources:
2866
+ selection = source_coverage_selection(relative, worker_id)
2867
+ (
2868
+ selected_coverage_superseded,
2869
+ selected_candidates,
2870
+ superseded,
2871
+ retain_pending,
2872
+ coverage_superseded,
2873
+ ) = selection
2874
+ skip_superseded_findings = (
2875
+ superseded
2876
+ and not stopped
2877
+ and all(
2878
+ valid_finding(finding) for finding in (parent["findings"] if parent else [])
2879
+ )
2880
+ )
2881
+ if (
2882
+ skip_superseded_findings
2883
+ and coverage_superseded
2884
+ and not selected_candidates
2885
+ and not retain_pending
2886
+ ):
2887
+ continue
2888
+ if (
2889
+ not dry_run
2890
+ and not skip_superseded_findings
2891
+ and "threatModel" not in manifest["scan"]
2892
+ and isinstance(draft.get("threatModel"), dict)
2893
+ ):
2894
+ model = recovered_model(relative, draft, worker_id)
2895
+ model_path = relative
2896
+ checkpoint_dir = Path(relative).parent
2897
+ root_checkpoint = checkpoint_dir == Path("checkpoints")
2898
+ prefer_checkpoint_head = root_checkpoint or (
2899
+ worker_id is not None
2900
+ and (checkpoint_dir.name == "checkpoints" or draft.get("complete") is False)
2901
+ )
2902
+ if worker_id is not None or root_checkpoint:
2903
+ if checkpoint_dir.name != "checkpoints":
2904
+ checkpoint_dir /= "checkpoints"
2905
+ selected_models = [
2906
+ path
2907
+ for path in drafts_by_path
2908
+ if (
2909
+ path in selected_observations
2910
+ or (
2911
+ path in current_results
2912
+ and drafts_by_path[path].get("complete") is not False
2913
+ )
2914
+ )
2915
+ and (
2916
+ Path(path).parent == checkpoint_dir
2917
+ or (
2918
+ path in current_results
2919
+ and Path(path).parent / "checkpoints" == checkpoint_dir
2920
+ )
2921
+ )
2922
+ and isinstance(drafts_by_path[path].get("threatModel"), dict)
2923
+ and recovered_model(path, drafts_by_path[path], worker_id) is not None
2924
+ ]
2925
+ if selected_models:
2926
+ authoritative_models = [
2927
+ path
2928
+ for path in selected_models
2929
+ if path in authoritative_heads or path in current_results
2930
+ ]
2931
+ if not any(path in authoritative_heads for path in selected_models):
2932
+ authoritative_models = selected_models
2933
+ head_path = max(
2934
+ authoritative_models or selected_models,
2935
+ key=lambda path: (source_order[path], path in authoritative_heads),
2936
+ )
2937
+ current = drafts_by_path[head_path]
2938
+ # A terminal checkpoint is committed before result.json is replaced.
2939
+ # Use the admitted observation, including its frozen ordering on retries.
2940
+ if not prefer_checkpoint_head and current.get("complete") is not False:
2941
+ prefer_checkpoint_head = (
2942
+ source_order[head_path] >= source_order[relative]
2943
+ )
2944
+ if prefer_checkpoint_head:
2945
+ model = recovered_model(head_path, current, worker_id)
2946
+ model_path = head_path
2947
+ if model is not None:
2948
+ manifest["scan"]["threatModel"] = model
2949
+ if selected_model_source is not None and model_path in source_digests:
2950
+ selected_model_source[:] = [model_path]
2951
+ if not dry_run:
2952
+ retain_findings(
2953
+ relative, draft, worker_id, selected_candidates, skip_superseded_findings
2954
+ )
2955
+ worker = workers_by_id.get(worker_id)
2956
+ # Only the accepted current output belongs to this worker attempt. An
2957
+ # unsuperseded archive can remain evidence after that output is lost.
2958
+ project_coverage = (
2959
+ worker is not None
2960
+ and worker["status"] == "succeeded"
2961
+ and worker["result_manifest_path"] == str(scan_dir / relative)
2962
+ and draft.get("complete") is not False
2963
+ )
2964
+ if coverage_superseded and not selected_candidates and not retain_pending:
2965
+ continue
2966
+ if project_coverage:
2967
+ reviewed_attempts.add((worker_id, worker["attempt"]))
2968
+ reviews = coverage.setdefault("reviews", [])
2969
+ if isinstance(reviews, list) and not any(
2970
+ isinstance(review, dict)
2971
+ and review.get("workerId") == worker_id
2972
+ and review.get("attempt") == worker["attempt"]
2973
+ for review in reviews
2974
+ ):
2975
+ reviews.append(
2976
+ {
2977
+ "workerId": worker_id,
2978
+ "attempt": worker["attempt"],
2979
+ "completeness": draft["reviewState"].get("completeness", "partial"),
2980
+ }
2981
+ )
2982
+ for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions", "reviews"):
2983
+ if field == "reviews" and (
2984
+ worker_id is not None or field not in draft["reviewState"]
2985
+ ):
2986
+ continue
2987
+ if coverage_superseded and field not in {
2988
+ "surfaces",
2989
+ "explicitExclusions",
2990
+ "deferred",
2991
+ }:
2992
+ continue
2993
+ items = draft["reviewState"].get(field, [])
2994
+ if field == "deferred":
2995
+ items = deferred_rows[relative]
2996
+ if not isinstance(items, list):
2997
+ continue
2998
+ output = coverage.setdefault(field, [])
2999
+ if not isinstance(output, list):
3000
+ # Keep malformed canonical collections for the existing finalizer's
3001
+ # recovery and warnings rather than silently changing its contract.
3002
+ continue
3003
+ for index, item in enumerate(items, 1):
3004
+ source_item = item
3005
+ if not (
3006
+ surface_is_retained(relative, worker_id, item)
3007
+ if field == "surfaces"
3008
+ else coverage_row_is_retained(field, item, worker_id, selection)
3009
+ ):
3010
+ continue
3011
+ if id(item) in replaced_rows.get(field, ()):
3012
+ continue
3013
+ if (
3014
+ field == "deferred"
3015
+ and isinstance(item, dict)
3016
+ and isinstance(item.get("id"), str)
3017
+ and record_key("deferred", worker_id, item) in closed_deferred
3018
+ ):
3019
+ continue
3020
+ if field == "openQuestions" and isinstance(item, str):
3021
+ item = {"question": item.strip()}
3022
+ if (
3023
+ field == "surfaces"
3024
+ and isinstance(item, dict)
3025
+ and item.get("disposition") in ("rejected", "not_applicable")
3026
+ and isinstance(item.get("candidateId"), str)
3027
+ and (
3028
+ history_findings := rejected_history.get(
3029
+ (worker_id, item["candidateId"])
3030
+ )
3031
+ )
3032
+ ):
3033
+ item = copy.deepcopy(item)
3034
+ for finding in history_findings:
3035
+ _append_previous_finding(item, finding, clone=True)
3036
+ projected_row = False
3037
+ if isinstance(item, dict):
3038
+ original_item = item
3039
+ item = (
3040
+ project_missing_record(field, item, index, worker, draft["reviewState"])
3041
+ if project_coverage
3042
+ else project_record(field, item, source_item)
3043
+ )
3044
+ projected_row = item is not original_item
3045
+ if field == "surfaces" and isinstance(item, dict):
3046
+ item = {**item, "receiptRefs": item.get("receiptRefs", [])}
3047
+ if (
3048
+ field == "surfaces"
3049
+ and worker is not None
3050
+ and isinstance(item, dict)
3051
+ and (project_coverage or not projected_row)
3052
+ ):
3053
+ item = copy.deepcopy(item)
3054
+ item["receiptRefs"] = coverage_receipts(item, worker, relative)
3055
+ if (
3056
+ projected_row
3057
+ and isinstance(item, dict)
3058
+ and retained_coverage_record(field, item) is not None
3059
+ ):
3060
+ continue
3061
+ if isinstance(item, dict) and "id" not in item:
3062
+ semantic_item = dict(item)
3063
+ existing = next(
3064
+ (
3065
+ existing
3066
+ for existing in output
3067
+ if isinstance(existing, dict)
3068
+ and {key: value for key, value in existing.items() if key != "id"}
3069
+ == semantic_item
3070
+ ),
3071
+ None,
3072
+ )
3073
+ if existing is not None:
3074
+ _inherit_coverage_sources(existing, [source_item], coverage_sources)
3075
+ if field == "surfaces":
3076
+ retained_surface_rows.add(id(source_item))
3077
+ continue
3078
+ retain_coverage_row(
3079
+ output,
3080
+ item,
3081
+ worker_id,
3082
+ field,
3083
+ source_item,
3084
+ projected_row or project_coverage,
3085
+ )
3086
+
3087
+ projection.finalize(
3088
+ coverage,
3089
+ canonical_rows,
3090
+ _digest,
3091
+ preserve_canonical_parent=preserve_canonical_parent,
3092
+ all_sources=all_sources,
3093
+ source_order=source_order,
3094
+ coverage_sources=coverage_sources,
3095
+ surface_ids_by_source=surface_ids_by_source,
3096
+ retained_surface_rows=retained_surface_rows,
3097
+ resolved=resolved,
3098
+ )
3099
+ if not dry_run:
3100
+ break
3101
+ invalid = _conflicting_outcome_receipts(
3102
+ coverage,
3103
+ scan_dir,
3104
+ competing_receipts - unavailable,
3105
+ )
3106
+ if invalid:
3107
+ unavailable.update(invalid)
3108
+ resolved, ordered_outcomes = select_outcomes(unavailable)
3109
+ else:
3110
+ dry_run = False
3111
+
3112
+ # Generate new worker identities from the retained collection, as a normal
3113
+ # Deep parent does. Authored, restored and canonical identities stay stable.
3114
+ generated_worker_ids = {id(finding) for finding in generated_worker_findings}
3115
+ for finding in generated_worker_findings:
3116
+ finding.pop("identity", None)
3117
+
3118
+ def publication_order(item):
3119
+ _, group = item
3120
+ source, value = group["observations"][group["owner"]]
3121
+ index = next(index for index, row in enumerate(source[1]["findings"]) if row is value)
3122
+ return finding_source_order(source, True), -index
3123
+
3124
+ identity_order = list(findings)
3125
+ for owner in {group["owner"] for _, group in finding_positions.values() if group is not None}:
3126
+ positions = [
3127
+ (position, group)
3128
+ for position, group in finding_positions.values()
3129
+ if group is not None and group["owner"] == owner and group["identity"] is None
3130
+ ]
3131
+
3132
+ for (position, _), (published_position, _) in zip(
3133
+ positions, sorted(positions, key=publication_order, reverse=True), strict=True
3134
+ ):
3135
+ identity_order[position] = findings[published_position]
3136
+ identity_order = [
3137
+ finding
3138
+ for finding in identity_order
3139
+ if valid_finding(finding) and ("identity" in finding or id(finding) in generated_worker_ids)
3140
+ ]
3141
+ _ensure_finding_identities(identity_order)
3142
+
3143
+ identities: dict[bytes, list[tuple[str, dict[str, Any] | None, str | None]]] = {}
3144
+ retained_groups = {
3145
+ position: group for position, group in finding_positions.values() if group is not None
3146
+ }
3147
+ reserved_identities = {_semantic_identity_key(finding) for finding in identity_order}
3148
+ for position, finding in enumerate(findings):
3149
+ if not valid_finding(finding):
3150
+ continue
3151
+ identity = finding.get("identity")
3152
+ if not isinstance(identity, dict):
3153
+ continue
3154
+ key = _semantic_identity_key(finding)
3155
+ variant = _finding_key(finding)
3156
+ group = retained_groups.get(position)
3157
+ previous = next(
3158
+ (
3159
+ entry
3160
+ for entry in identities.get(key, [])
3161
+ if entry[0] == variant and not distinct_reports(group, entry[1])
3162
+ ),
3163
+ None,
3164
+ )
3165
+ if previous is not None and previous[2] is not None:
3166
+ if identity.get("instance") != previous[2]:
3167
+ finding.setdefault("provenance", {}).setdefault(
3168
+ "preservedIdentity", copy.deepcopy(identity)
3169
+ )
3170
+ identity["instance"] = previous[2]
3171
+ elif previous is None and key in identities:
3172
+ finding.setdefault("provenance", {}).setdefault(
3173
+ "preservedIdentity", copy.deepcopy(identity)
3174
+ )
3175
+ base_instance = identity.get("instance", "saved")
3176
+ suffix = 2
3177
+ while True:
3178
+ identity["instance"] = f"{base_instance}-{suffix}"
3179
+ distinct = _semantic_identity_key(finding)
3180
+ if distinct not in reserved_identities:
3181
+ reserved_identities.add(distinct)
3182
+ break
3183
+ suffix += 1
3184
+ identities.setdefault(key, []).append((variant, group, identity.get("instance")))
3185
+ coverage.pop("completeness", None)
3186
+ if stopped:
3187
+ if not isinstance(coverage.get("deferred"), list):
3188
+ coverage["deferred"] = []
3189
+ item = {"id": "scan-stopped", "reason": reason}
3190
+ if item not in coverage["deferred"]:
3191
+ coverage["deferred"].append(item)
3192
+ surfaces = coverage.get("surfaces", [])
3193
+ for surface in surfaces if isinstance(surfaces, list) else []:
3194
+ if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
3195
+ surface["provenance"].pop("scanReceiptRefs", None)
3196
+ if (
3197
+ frozen_source_digests is None
3198
+ or heads_snapshotted
3199
+ or snapshot_error is not None
3200
+ or any(_is_source_order_snapshot(path) for path in source_digests)
3201
+ or allow_frozen_legacy_parent
3202
+ ):
3203
+ try:
3204
+ if snapshot_error is not None:
3205
+ raise snapshot_error
3206
+ _freeze_source_times(
3207
+ scan_dir,
3208
+ scan_id,
3209
+ source_digests,
3210
+ source_times,
3211
+ parent_context,
3212
+ created_paths=created_paths,
3213
+ )
3214
+ except (ContractError, OSError) as exc:
3215
+ failure = _CheckpointSnapshotError(
3216
+ str(exc),
3217
+ {
3218
+ path: (digest, source_times[path])
3219
+ for path, digest in source_digests.items()
3220
+ if not _is_source_order_snapshot(path)
3221
+ },
3222
+ )
3223
+ failure.parent_context = parent_context
3224
+ failure.heads = checkpoint_heads
3225
+ failure.documents = (manifest, {"findings": findings}, coverage)
3226
+ if isinstance(manifest["scan"].get("threatModel"), dict):
3227
+ failure.model_source = list(selected_model_source or [])
3228
+ raise failure from exc
3229
+
3230
+ return manifest, {"findings": findings}, coverage