@openai/codex-security 0.7.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 (153) hide show
  1. package/README.md +10 -4
  2. package/_bundled_plugin/examples/completed-scan/findings.json +34 -34
  3. package/_bundled_plugin/examples/completed-scan/report.md +22 -31
  4. package/_bundled_plugin/examples/completed-scan/scan-manifest.json +27 -29
  5. package/_bundled_plugin/examples/{completed-scan → legacy-completed-scan}/coverage.json +1 -0
  6. package/_bundled_plugin/examples/legacy-completed-scan/findings.json +57 -0
  7. package/_bundled_plugin/examples/legacy-completed-scan/report.md +98 -0
  8. package/_bundled_plugin/examples/legacy-completed-scan/scan-manifest.json +43 -0
  9. package/_bundled_plugin/mcp/helpers.mjs.br.part-000 +0 -0
  10. package/_bundled_plugin/mcp/helpers.mjs.br.part-001 +0 -0
  11. package/_bundled_plugin/mcp/native/win32-arm64/windows.node +0 -0
  12. package/_bundled_plugin/mcp/native/win32-x64/windows.node +0 -0
  13. package/_bundled_plugin/mcp/server.mjs.br.part-000 +0 -0
  14. package/_bundled_plugin/mcp/server.mjs.br.part-001 +0 -0
  15. package/_bundled_plugin/mcp/server.mjs.br.part-002 +0 -0
  16. package/_bundled_plugin/references/core-scan.md +2 -2
  17. package/_bundled_plugin/references/final-report.md +16 -6
  18. package/_bundled_plugin/references/scan-artifacts.md +5 -5
  19. package/_bundled_plugin/references/scan-contract.md +10 -12
  20. package/_bundled_plugin/references/threat-model.md +1 -1
  21. package/_bundled_plugin/schemas/scan-manifest.schema.json +36 -11
  22. package/_bundled_plugin/schemas/tools/scan-draft.schema.json +5 -5
  23. package/_bundled_plugin/scripts/deep_scan_workbench.py +1 -1
  24. package/_bundled_plugin/scripts/finalize_scan_contract.py +60 -19
  25. package/_bundled_plugin/scripts/report_projection.py +5 -2
  26. package/_bundled_plugin/scripts/review_state.py +68 -0
  27. package/_bundled_plugin/scripts/validate_scan_contract.py +1 -2
  28. package/_bundled_plugin/scripts/workbench/retained_coverage.py +49 -37
  29. package/_bundled_plugin/scripts/workbench/retained_records.py +7 -7
  30. package/_bundled_plugin/scripts/workbench/saved_coverage.py +15 -15
  31. package/_bundled_plugin/scripts/workbench/saved_sources.py +24 -6
  32. package/_bundled_plugin/scripts/workbench_constants.py +0 -1
  33. package/_bundled_plugin/scripts/workbench_coverage_receipts.py +4 -4
  34. package/_bundled_plugin/scripts/workbench_db.py +5 -150
  35. package/_bundled_plugin/scripts/workbench_saved_results.py +169 -4
  36. package/_bundled_plugin/scripts/workbench_scan_history.py +12 -7
  37. package/_bundled_plugin/skills/publish-findings/SKILL.md +5 -1
  38. package/_bundled_plugin/skills/security-diff-scan/SKILL.md +1 -1
  39. package/_bundled_plugin/skills/security-scan/SKILL.md +6 -6
  40. package/_bundled_plugin/skills/track-findings/SKILL.md +1 -1
  41. package/dist/api.d.ts.map +1 -1
  42. package/dist/api.js +19 -17
  43. package/dist/api.js.map +1 -1
  44. package/dist/cli.d.ts.map +1 -1
  45. package/dist/cli.js +28 -17
  46. package/dist/cli.js.map +1 -1
  47. package/dist/cloud-publish.d.ts.map +1 -1
  48. package/dist/cloud-publish.js +2 -23
  49. package/dist/cloud-publish.js.map +1 -1
  50. package/dist/contract.d.ts +3 -2
  51. package/dist/contract.d.ts.map +1 -1
  52. package/dist/contract.js +28 -14
  53. package/dist/contract.js.map +1 -1
  54. package/dist/custom-publish.js +2 -2
  55. package/dist/custom-publish.js.map +1 -1
  56. package/dist/custom-validation-prompt.js +5 -5
  57. package/dist/custom-validation-prompt.js.map +1 -1
  58. package/dist/custom-validation.d.ts.map +1 -1
  59. package/dist/custom-validation.js +17 -15
  60. package/dist/custom-validation.js.map +1 -1
  61. package/dist/deduplication/codex-review.d.ts.map +1 -1
  62. package/dist/deduplication/codex-review.js +2 -2
  63. package/dist/deduplication/codex-review.js.map +1 -1
  64. package/dist/deduplication/deduplication-prompts.d.ts +1 -0
  65. package/dist/deduplication/deduplication-prompts.d.ts.map +1 -1
  66. package/dist/deduplication/deduplication-prompts.js +3 -0
  67. package/dist/deduplication/deduplication-prompts.js.map +1 -1
  68. package/dist/deduplication/records-protocol.d.ts.map +1 -1
  69. package/dist/deduplication/records-protocol.js +21 -1
  70. package/dist/deduplication/records-protocol.js.map +1 -1
  71. package/dist/deduplication/scan.d.ts.map +1 -1
  72. package/dist/deduplication/scan.js +2 -2
  73. package/dist/deduplication/scan.js.map +1 -1
  74. package/dist/external-findings-local.d.ts +1 -0
  75. package/dist/external-findings-local.d.ts.map +1 -1
  76. package/dist/external-findings-local.js +6 -2
  77. package/dist/external-findings-local.js.map +1 -1
  78. package/dist/external-findings-publish.d.ts +1 -0
  79. package/dist/external-findings-publish.d.ts.map +1 -1
  80. package/dist/external-findings-publish.js +53 -25
  81. package/dist/external-findings-publish.js.map +1 -1
  82. package/dist/external-findings-read.d.ts +1 -0
  83. package/dist/external-findings-read.d.ts.map +1 -1
  84. package/dist/external-findings-read.js +10 -0
  85. package/dist/external-findings-read.js.map +1 -1
  86. package/dist/external-findings.d.ts +2 -0
  87. package/dist/external-findings.d.ts.map +1 -1
  88. package/dist/external-findings.js.map +1 -1
  89. package/dist/external-import-contract.d.ts +4 -0
  90. package/dist/external-import-contract.d.ts.map +1 -1
  91. package/dist/external-import-contract.js +34 -10
  92. package/dist/external-import-contract.js.map +1 -1
  93. package/dist/finding-workflow.d.ts +2 -0
  94. package/dist/finding-workflow.d.ts.map +1 -1
  95. package/dist/finding-workflow.js +3 -0
  96. package/dist/finding-workflow.js.map +1 -1
  97. package/dist/host-protocol.d.ts +1 -1
  98. package/dist/host-protocol.d.ts.map +1 -1
  99. package/dist/host-protocol.js +2 -2
  100. package/dist/host-protocol.js.map +1 -1
  101. package/dist/hosted-scan.d.ts.map +1 -1
  102. package/dist/hosted-scan.js +0 -1
  103. package/dist/hosted-scan.js.map +1 -1
  104. package/dist/import-scan.js +16 -16
  105. package/dist/import-scan.js.map +1 -1
  106. package/dist/index.d.ts +1 -0
  107. package/dist/index.d.ts.map +1 -1
  108. package/dist/index.js +1 -0
  109. package/dist/index.js.map +1 -1
  110. package/dist/knowledge-base.js +3 -0
  111. package/dist/knowledge-base.js.map +1 -1
  112. package/dist/mock-scan.d.ts +1 -2
  113. package/dist/mock-scan.d.ts.map +1 -1
  114. package/dist/mock-scan.js +12 -17
  115. package/dist/mock-scan.js.map +1 -1
  116. package/dist/models.d.ts +9 -1
  117. package/dist/models.d.ts.map +1 -1
  118. package/dist/models.js.map +1 -1
  119. package/dist/multiscan.d.ts.map +1 -1
  120. package/dist/multiscan.js +1 -6
  121. package/dist/multiscan.js.map +1 -1
  122. package/dist/native-json-findings.d.ts +30 -0
  123. package/dist/native-json-findings.d.ts.map +1 -0
  124. package/dist/native-json-findings.js +114 -0
  125. package/dist/native-json-findings.js.map +1 -0
  126. package/dist/opengrep-findings.d.ts +10 -0
  127. package/dist/opengrep-findings.d.ts.map +1 -0
  128. package/dist/opengrep-findings.js +198 -0
  129. package/dist/opengrep-findings.js.map +1 -0
  130. package/dist/patch-tui.d.ts.map +1 -1
  131. package/dist/patch-tui.js +2 -0
  132. package/dist/patch-tui.js.map +1 -1
  133. package/dist/publication.js +1 -2
  134. package/dist/publication.js.map +1 -1
  135. package/dist/record.d.ts +1 -0
  136. package/dist/record.d.ts.map +1 -1
  137. package/dist/record.js +10 -0
  138. package/dist/record.js.map +1 -1
  139. package/dist/result.d.ts +5 -3
  140. package/dist/result.d.ts.map +1 -1
  141. package/dist/result.js +9 -6
  142. package/dist/result.js.map +1 -1
  143. package/dist/scan-history-renderer.js +1 -1
  144. package/dist/scan-history-renderer.js.map +1 -1
  145. package/dist/security-policy.d.ts.map +1 -1
  146. package/dist/security-policy.js +16 -2
  147. package/dist/security-policy.js.map +1 -1
  148. package/dist/semgrep-findings.d.ts.map +1 -1
  149. package/dist/semgrep-findings.js +15 -82
  150. package/dist/semgrep-findings.js.map +1 -1
  151. package/docs/cli.md +16 -3
  152. package/docs/dedupe-records.md +15 -1
  153. package/package.json +3 -3
@@ -20,6 +20,7 @@ from finalize_scan_contract import (
20
20
  finding_candidate_id,
21
21
  write_scan_local_bytes,
22
22
  )
23
+ from review_state import uses_legacy_review
23
24
  from workbench.retained_records import (
24
25
  _append_previous_finding,
25
26
  _competing_rejection_receipts,
@@ -172,8 +173,13 @@ def merge_saved_results(
172
173
  ):
173
174
  try:
174
175
  parent_manifest, parent = _read_saved_parent_result(scan_dir, scan_id)
175
- # Without an accepted head, file-authored coverage is a full replacement.
176
- parent_modified = (scan_dir / "coverage.json").lstat().st_mtime_ns
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
177
183
  parent_is_canonical = True
178
184
  except (ContractError, OSError, ValueError) as exc:
179
185
  if not stopped:
@@ -192,7 +198,11 @@ def merge_saved_results(
192
198
  # A partial tool publication must not outrank its accepted head.
193
199
  parent_modified = min(
194
200
  (scan_dir / name).lstat().st_mtime_ns
195
- for name in ("findings.json", "coverage.json", "scan-manifest.json")
201
+ for name in (
202
+ "findings.json",
203
+ "scan-manifest.json",
204
+ *(["coverage.json"] if uses_legacy_review(parent_scan) else []),
205
+ )
196
206
  )
197
207
  if not parent_scan.get("sealedAt") or allow_frozen_legacy_parent:
198
208
  payload = _encoded(parent)
@@ -374,7 +384,7 @@ def merge_saved_results(
374
384
  discarded_by_source[relative] = discarded
375
385
  # Recovery expects coverage, but reducer results only contain findings
376
386
  # and context. Add an empty value after hashing the original result.
377
- sources.append((relative, {"coverage": {}, **draft}, worker_id))
387
+ sources.append((relative, {"reviewState": {}, **draft}, worker_id))
378
388
  if frozen_source_digests is None:
379
389
  pending.extend(
380
390
  receipt_checkpoints(
@@ -521,7 +531,7 @@ def merge_saved_results(
521
531
  parent_model_source = relative
522
532
  parent_is_canonical = draft.get("canonicalParent") is True
523
533
  break
524
- projected_coverage = parent["coverage"] if parent else {}
534
+ projected_coverage = parent["reviewState"] if parent else {}
525
535
  # V1 persists the review projection in the parent, without reducer sourceCoverage.
526
536
 
527
537
  coverage_receipts = partial(resolve_coverage_receipts, scan_dir)
@@ -719,7 +729,7 @@ def merge_saved_results(
719
729
  parent = drafts_by_path[latest_reducer]
720
730
  parent_model_source = latest_reducer
721
731
 
722
- projected_coverage = saved_parent["coverage"] if saved_parent else {}
732
+ projected_coverage = saved_parent["reviewState"] if saved_parent else {}
723
733
  reviews = projected_coverage.get("reviews")
724
734
  reviewed_attempts = {
725
735
  (review.get("workerId"), review.get("attempt"))
@@ -767,13 +777,13 @@ def merge_saved_results(
767
777
  return retained
768
778
 
769
779
  accepted_coverage_sources = {
770
- id(draft["coverage"]) for relative, draft, _ in sources if relative in accepted_sources
780
+ id(draft["reviewState"]) for relative, draft, _ in sources if relative in accepted_sources
771
781
  }
772
782
  accepted_surfaces: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = {}
773
783
  for relative, draft, worker_id in sources:
774
784
  if relative not in accepted_sources:
775
785
  continue
776
- surfaces = draft["coverage"].get("surfaces", [])
786
+ surfaces = draft["reviewState"].get("surfaces", [])
777
787
  for index, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
778
788
  if isinstance(surface, dict) and isinstance(surface.get("id"), str):
779
789
  accepted_surfaces.setdefault((worker_id, surface["id"]), []).append(
@@ -781,18 +791,18 @@ def merge_saved_results(
781
791
  )
782
792
 
783
793
  for _, draft, _ in sources:
784
- questions = draft["coverage"].get("openQuestions")
794
+ questions = draft["reviewState"].get("openQuestions")
785
795
  if isinstance(questions, list):
786
- draft["coverage"]["openQuestions"] = [
796
+ draft["reviewState"]["openQuestions"] = [
787
797
  {"question": item.strip()} if isinstance(item, str) else item for item in questions
788
798
  ]
789
799
  projection_origins = {
790
- id(item): (worker_id, relative, field, index, draft["coverage"])
800
+ id(item): (worker_id, relative, field, index, draft["reviewState"])
791
801
  for relative, draft, worker_id in sources
792
802
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions")
793
803
  for index, item in enumerate(
794
- draft["coverage"].get(field, [])
795
- if isinstance(draft["coverage"].get(field, []), list)
804
+ draft["reviewState"].get(field, [])
805
+ if isinstance(draft["reviewState"].get(field, []), list)
796
806
  else [],
797
807
  1,
798
808
  )
@@ -825,7 +835,7 @@ def merge_saved_results(
825
835
  # accepted worker's surface namespace.
826
836
  accepted = next(
827
837
  (
828
- (path, draft["coverage"])
838
+ (path, draft["reviewState"])
829
839
  for path, draft, owner in sources
830
840
  if owner == worker_id and path in accepted_sources
831
841
  ),
@@ -859,11 +869,11 @@ def merge_saved_results(
859
869
  for _, draft, owner in all_sources:
860
870
  named_rows.setdefault(owner, []).extend(
861
871
  row
862
- for row in _coverage_rows(draft["coverage"], field)
872
+ for row in _coverage_rows(draft["reviewState"], field)
863
873
  if isinstance(row, dict) and isinstance(row.get("id"), str)
864
874
  )
865
875
  for _, draft, owner in all_sources:
866
- rows = _coverage_rows(draft["coverage"], field)
876
+ rows = _coverage_rows(draft["reviewState"], field)
867
877
  reserved = {
868
878
  row["id"]
869
879
  for row in rows
@@ -898,8 +908,8 @@ def merge_saved_results(
898
908
  (relative, row["id"]): []
899
909
  for relative, draft, _ in all_sources
900
910
  for row in (
901
- draft["coverage"].get("surfaces", [])
902
- if isinstance(draft["coverage"].get("surfaces"), list)
911
+ draft["reviewState"].get("surfaces", [])
912
+ if isinstance(draft["reviewState"].get("surfaces"), list)
903
913
  else []
904
914
  )
905
915
  if isinstance(row, dict) and isinstance(row.get("id"), str)
@@ -951,7 +961,7 @@ def merge_saved_results(
951
961
  )
952
962
  if allow_frozen_legacy_parent:
953
963
  manifest["scan"]["target"] = target
954
- for key in ("sealedAt", "artifacts"):
964
+ for key in ("sealedAt", "artifacts", "coverageRef"):
955
965
  manifest["scan"].pop(key, None)
956
966
  manifest["scan"]["preservedSources"] = source_digests
957
967
  manifest["scan"]["preservedCheckpointHeads"] = checkpoint_heads
@@ -1120,8 +1130,8 @@ def merge_saved_results(
1120
1130
  if selected_model_source is not None:
1121
1131
  selected_model_source[:] = [] if model is None else [frozen_model_source]
1122
1132
  coverage = (
1123
- copy.deepcopy(parent["coverage"])
1124
- if parent and parent["coverage"]
1133
+ copy.deepcopy(parent["reviewState"])
1134
+ if parent and parent["reviewState"]
1125
1135
  else {
1126
1136
  "mode": binding["coverageMode"],
1127
1137
  "inventoryStrategy": "diff"
@@ -1145,7 +1155,7 @@ def merge_saved_results(
1145
1155
  {
1146
1156
  id(item)
1147
1157
  for parent_coverage in (
1148
- (coverage, parent["coverage"]) if preserve_canonical_parent else (coverage,)
1158
+ (coverage, parent["reviewState"]) if preserve_canonical_parent else (coverage,)
1149
1159
  )
1150
1160
  for field in ("surfaces", "explicitExclusions", "deferred")
1151
1161
  for item in _coverage_rows(parent_coverage, field)
@@ -1159,7 +1169,7 @@ def merge_saved_results(
1159
1169
  retained_surface_rows: set[int] = set()
1160
1170
  for relative, draft, _ in all_sources:
1161
1171
  for field in ("surfaces", "deferred"):
1162
- rows = draft["coverage"].get(field)
1172
+ rows = draft["reviewState"].get(field)
1163
1173
  for row in rows if isinstance(rows, list) else []:
1164
1174
  if isinstance(row, dict):
1165
1175
  paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
@@ -1167,7 +1177,7 @@ def merge_saved_results(
1167
1177
  paths_for_row.append(relative)
1168
1178
  if parent:
1169
1179
  for field in ("surfaces", "deferred"):
1170
- rows, originals = coverage.get(field), parent["coverage"].get(field)
1180
+ rows, originals = coverage.get(field), parent["reviewState"].get(field)
1171
1181
  if isinstance(rows, list) and isinstance(originals, list):
1172
1182
  for row, original in zip(rows, originals):
1173
1183
  _inherit_coverage_sources(row, [original], coverage_sources)
@@ -1320,7 +1330,7 @@ def merge_saved_results(
1320
1330
  if isinstance(finding, dict) and valid_finding(finding)
1321
1331
  }
1322
1332
  for field in ("surfaces", "deferred", "explicitExclusions"):
1323
- rows = draft["coverage"].get(field, [])
1333
+ rows = draft["reviewState"].get(field, [])
1324
1334
  for index, row in enumerate(rows if isinstance(rows, list) else [], 1):
1325
1335
  if not isinstance(row, dict):
1326
1336
  continue
@@ -1332,7 +1342,7 @@ def merge_saved_results(
1332
1342
  < source_order[relative]
1333
1343
  ):
1334
1344
  accepted_pending_candidates.add((worker_id, worker["attempt"], candidate_id))
1335
- projected = project_missing_record(field, row, index, worker, draft["coverage"])
1345
+ projected = project_missing_record(field, row, index, worker, draft["reviewState"])
1336
1346
  if field == "surfaces":
1337
1347
  projected["receiptRefs"] = coverage_receipts(projected, worker, relative)
1338
1348
  key = projection_key(field, projected)
@@ -1398,7 +1408,7 @@ def merge_saved_results(
1398
1408
  return order
1399
1409
 
1400
1410
  deferred_rows = {
1401
- relative: _coverage_rows(draft["coverage"], "deferred")
1411
+ relative: _coverage_rows(draft["reviewState"], "deferred")
1402
1412
  for relative, draft, _ in all_sources
1403
1413
  }
1404
1414
  # Accepted heads can replace equal tasks before they reach output coalescing.
@@ -1443,7 +1453,7 @@ def merge_saved_results(
1443
1453
 
1444
1454
  pending_surface_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
1445
1455
  for relative, draft, owner in all_sources:
1446
- surfaces = draft["coverage"].get("surfaces", [])
1456
+ surfaces = draft["reviewState"].get("surfaces", [])
1447
1457
  for surface in surfaces if isinstance(surfaces, list) else []:
1448
1458
  if (
1449
1459
  isinstance(surface, dict)
@@ -1787,7 +1797,7 @@ def merge_saved_results(
1787
1797
  relative == "parent"
1788
1798
  or relative == parent_context.get("canonical")
1789
1799
  # The semantic tool schema forbids this host-owned projection field.
1790
- or draft["coverage"].get("mode") == binding["coverageMode"]
1800
+ or draft["reviewState"].get("mode") == binding["coverageMode"]
1791
1801
  )
1792
1802
  }
1793
1803
  projected_parents = [draft for relative, draft, _ in all_sources if relative in projected_paths]
@@ -2368,7 +2378,7 @@ def merge_saved_results(
2368
2378
  }
2369
2379
  for _, draft, owner in all_sources:
2370
2380
  by_id: dict[str, dict[str, Any]] = {}
2371
- for surface in _coverage_rows(draft["coverage"], "surfaces"):
2381
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
2372
2382
  if not isinstance(surface, dict) or not isinstance(identity := surface.get("id"), str):
2373
2383
  continue
2374
2384
  if identity in by_id and surface != by_id[identity]:
@@ -2717,7 +2727,7 @@ def merge_saved_results(
2717
2727
  for owner, row in prospective_tasks:
2718
2728
  retain_surface_links(owner, row)
2719
2729
  if parent and isinstance(coverage.get("deferred"), list):
2720
- previous = parent["coverage"].get("deferred", [])
2730
+ previous = parent["reviewState"].get("deferred", [])
2721
2731
  removed_parent = (
2722
2732
  [row for row in previous if id(row) in replaced_deferred]
2723
2733
  if isinstance(previous, list)
@@ -2775,7 +2785,7 @@ def merge_saved_results(
2775
2785
  }
2776
2786
  for field, replaced in replaced_rows.items():
2777
2787
  if parent and isinstance(coverage.get(field), list):
2778
- previous = parent["coverage"].get(field, [])
2788
+ previous = parent["reviewState"].get(field, [])
2779
2789
  if isinstance(previous, list):
2780
2790
  removed_parent = [row for row in previous if id(row) in replaced]
2781
2791
  coverage[field] = [row for row in coverage[field] if row not in removed_parent]
@@ -2832,7 +2842,7 @@ def merge_saved_results(
2832
2842
  pending, item, owner, "deferred", original_item, item is not original_item
2833
2843
  )
2834
2844
  for _, draft, owner in all_sources:
2835
- for surface in _coverage_rows(draft["coverage"], "surfaces"):
2845
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
2836
2846
  if (
2837
2847
  isinstance(surface, dict)
2838
2848
  and ambiguous_pending_surface(surface, owner)
@@ -2966,11 +2976,13 @@ def merge_saved_results(
2966
2976
  {
2967
2977
  "workerId": worker_id,
2968
2978
  "attempt": worker["attempt"],
2969
- "completeness": draft["coverage"].get("completeness", "partial"),
2979
+ "completeness": draft["reviewState"].get("completeness", "partial"),
2970
2980
  }
2971
2981
  )
2972
2982
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions", "reviews"):
2973
- if field == "reviews" and (worker_id is not None or field not in draft["coverage"]):
2983
+ if field == "reviews" and (
2984
+ worker_id is not None or field not in draft["reviewState"]
2985
+ ):
2974
2986
  continue
2975
2987
  if coverage_superseded and field not in {
2976
2988
  "surfaces",
@@ -2978,7 +2990,7 @@ def merge_saved_results(
2978
2990
  "deferred",
2979
2991
  }:
2980
2992
  continue
2981
- items = draft["coverage"].get(field, [])
2993
+ items = draft["reviewState"].get(field, [])
2982
2994
  if field == "deferred":
2983
2995
  items = deferred_rows[relative]
2984
2996
  if not isinstance(items, list):
@@ -3025,7 +3037,7 @@ def merge_saved_results(
3025
3037
  if isinstance(item, dict):
3026
3038
  original_item = item
3027
3039
  item = (
3028
- project_missing_record(field, item, index, worker, draft["coverage"])
3040
+ project_missing_record(field, item, index, worker, draft["reviewState"])
3029
3041
  if project_coverage
3030
3042
  else project_record(field, item, source_item)
3031
3043
  )
@@ -306,7 +306,7 @@ def _recover_preserved_worker_source(
306
306
  warnings.extend(f"{relative} finding {index + 1}: {warning}" for warning in source_warnings)
307
307
  draft["findings"] = recovered_findings
308
308
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
309
- rows = draft["coverage"].get(field)
309
+ rows = draft["reviewState"].get(field)
310
310
  if not isinstance(rows, list):
311
311
  continue
312
312
  for index, row in enumerate(rows):
@@ -330,7 +330,7 @@ def _recover_preserved_worker_coverage(
330
330
  ):
331
331
  discarded_coverage = False
332
332
  for field in ("surfaces", "explicitExclusions", "deferred"):
333
- rows = draft["coverage"].get(field)
333
+ rows = draft["reviewState"].get(field)
334
334
  for row in rows if isinstance(rows, list) else []:
335
335
  if isinstance(row, dict):
336
336
  row.setdefault("id", _saved_coverage_id(row))
@@ -338,7 +338,7 @@ def _recover_preserved_worker_coverage(
338
338
  row.setdefault("receiptRefs", [])
339
339
  source_warnings = []
340
340
  discarded_fields = _recover_unsealed_coverage(
341
- draft["coverage"],
341
+ draft["reviewState"],
342
342
  Path(__file__).resolve().parents[2] / "schemas",
343
343
  scan_dir,
344
344
  source_warnings,
@@ -353,7 +353,7 @@ def _recover_preserved_worker_coverage(
353
353
  "resolvedDeferred",
354
354
  }:
355
355
  discarded_coverage = True
356
- for row in draft["coverage"]["deferred"]:
356
+ for row in draft["reviewState"]["deferred"]:
357
357
  row["workerId"] = worker_id
358
358
  warnings.extend(f"{relative}: {warning}" for warning in source_warnings)
359
359
  return discarded_coverage
@@ -539,7 +539,7 @@ def _saved_candidate_outcomes(
539
539
  }
540
540
  pending_candidates = set()
541
541
  for field in ("deferred", "surfaces"):
542
- items = draft["coverage"].get(field, [])
542
+ items = draft["reviewState"].get(field, [])
543
543
  for item in items if isinstance(items, list) else []:
544
544
  if isinstance(item, dict) and (
545
545
  field == "deferred" or item.get("disposition") == "needs_follow_up"
@@ -573,7 +573,7 @@ def _saved_candidate_outcomes(
573
573
  )
574
574
  )
575
575
  for field in ("surfaces", "explicitExclusions"):
576
- for item in _coverage_rows(draft["coverage"], field):
576
+ for item in _coverage_rows(draft["reviewState"], field):
577
577
  if (
578
578
  isinstance(item, dict)
579
579
  and isinstance(item.get("candidateId"), str)
@@ -617,7 +617,7 @@ def _competing_rejection_receipts(outcomes, all_sources, source_surface_receipts
617
617
  and (spellings := receipt_spellings.get(Path(ref).as_posix().lower())) is not None
618
618
  and spellings != {Path(ref).as_posix()}
619
619
  for relative, draft, owner in all_sources
620
- for row in _coverage_rows(draft["coverage"], "surfaces")
620
+ for row in _coverage_rows(draft["reviewState"], "surfaces")
621
621
  if isinstance(row, dict)
622
622
  for refs in (source_surface_receipts(relative, row),)
623
623
  if isinstance(refs, list)
@@ -157,8 +157,8 @@ def _prepare_worker_coverage_recovery(
157
157
  for draft in parents
158
158
  for field in fields
159
159
  for row in (
160
- draft["coverage"].get(field, [])
161
- if isinstance(draft["coverage"].get(field, []), list)
160
+ draft["reviewState"].get(field, [])
161
+ if isinstance(draft["reviewState"].get(field, []), list)
162
162
  else []
163
163
  )
164
164
  )
@@ -177,7 +177,7 @@ def _prepare_worker_coverage_recovery(
177
177
  if directory.name == "checkpoints":
178
178
  directory = directory.parent
179
179
  for field in fields:
180
- rows = draft["coverage"].get(field, [])
180
+ rows = draft["reviewState"].get(field, [])
181
181
  if not isinstance(rows, list):
182
182
  continue
183
183
  for index, row in enumerate(rows):
@@ -219,13 +219,13 @@ def _prepare_worker_coverage_recovery(
219
219
  # the existing per-worker chronology reconcile those originals exactly once.
220
220
  # Keep parent-only evidence when its bound worker source is unavailable.
221
221
  for draft in parents:
222
- if not draft["coverage"]:
222
+ if not draft["reviewState"]:
223
223
  continue
224
224
  for field in fields:
225
- rows = draft["coverage"].get(field, [])
225
+ rows = draft["reviewState"].get(field, [])
226
226
  if isinstance(rows, list):
227
227
  if field == "surfaces":
228
- tasks = draft["coverage"].get("deferred", [])
228
+ tasks = draft["reviewState"].get("deferred", [])
229
229
  for row in rows:
230
230
  if not isinstance(row, dict) or not isinstance(row.get("id"), str):
231
231
  continue
@@ -259,7 +259,7 @@ def _prepare_worker_coverage_recovery(
259
259
  )
260
260
  for source in matching_sources
261
261
  )
262
- draft["coverage"][field] = [
262
+ draft["reviewState"][field] = [
263
263
  row
264
264
  for row in rows
265
265
  if _coverage_comparison_row(row, field) not in projected[field]
@@ -280,7 +280,7 @@ class SavedCoverageProjection:
280
280
  id(row): owner
281
281
  for _, draft, owner in sources
282
282
  for field in ("surfaces", "deferred")
283
- for rows in (draft["coverage"].get(field, []),)
283
+ for rows in (draft["reviewState"].get(field, []),)
284
284
  if isinstance(rows, list)
285
285
  for row in rows
286
286
  if isinstance(row, dict)
@@ -644,7 +644,7 @@ class SavedCoverageProjection:
644
644
  # tasks. Preserve their original links, even when the outcome changes ID
645
645
  # or a distinct retained surface shares the old source-local ID.
646
646
  for relative, draft, owner in all_sources:
647
- originals = draft["coverage"].get("surfaces", [])
647
+ originals = draft["reviewState"].get("surfaces", [])
648
648
  for original in originals if isinstance(originals, list) else []:
649
649
  if (
650
650
  not isinstance(original, dict)
@@ -686,7 +686,7 @@ class SavedCoverageProjection:
686
686
  prospective_surfaces = {}
687
687
  prospective_named = {}
688
688
  for relative, draft, owner in all_sources:
689
- rows = draft["coverage"].get("surfaces", [])
689
+ rows = draft["reviewState"].get("surfaces", [])
690
690
  for row in rows if isinstance(rows, list) else []:
691
691
  if owner is None or not isinstance(row, dict):
692
692
  continue
@@ -745,7 +745,7 @@ def prepare_saved_coverage_projection(
745
745
  id(row): ("workerId" in row, row.get("workerId"))
746
746
  for relative, draft, _ in sources
747
747
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions")
748
- for rows in (draft["coverage"].get(field, []),)
748
+ for rows in (draft["reviewState"].get(field, []),)
749
749
  if isinstance(rows, list)
750
750
  for row in rows
751
751
  if isinstance(row, dict)
@@ -759,7 +759,7 @@ def prepare_saved_coverage_projection(
759
759
  )
760
760
  for _, draft, _ in sources:
761
761
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
762
- rows = draft["coverage"].get(field, [])
762
+ rows = draft["reviewState"].get(field, [])
763
763
  if not isinstance(rows, list):
764
764
  continue
765
765
  for row in rows:
@@ -781,7 +781,7 @@ def _deferred_rows(coverage: dict[str, Any]) -> list[Any]:
781
781
  def _resolved_deferred_rows(draft: dict[str, Any], schema: dict[str, Any]) -> list[dict[str, Any]]:
782
782
  if draft.get("complete") is False:
783
783
  return []
784
- coverage = draft["coverage"]
784
+ coverage = draft["reviewState"]
785
785
  rows = coverage.get("resolvedDeferred", [])
786
786
  try:
787
787
  # Invalid closure metadata cannot discard the evidence it names.
@@ -845,9 +845,9 @@ def _merge_tied_parent_observations(
845
845
  for finding in previous["findings"]:
846
846
  if finding not in merged["findings"]:
847
847
  merged["findings"].append(copy.deepcopy(finding))
848
- coverage = merged["coverage"]
848
+ coverage = merged["reviewState"]
849
849
  for field in ("surfaces", "explicitExclusions", "deferred", "openQuestions"):
850
- rows = previous["coverage"].get(field, [])
850
+ rows = previous["reviewState"].get(field, [])
851
851
  output = coverage.setdefault(field, [])
852
852
  if isinstance(rows, list) and isinstance(output, list):
853
853
  for row in rows:
@@ -20,6 +20,7 @@ from finalize_scan_contract import (
20
20
  manifest_is_sealed,
21
21
  write_scan_local_bytes,
22
22
  )
23
+ from review_state import review_state, uses_legacy_review
23
24
  from workbench_coverage_receipts import capture_receipt_checkpoints
24
25
 
25
26
 
@@ -211,7 +212,12 @@ def _capture_saved_source(
211
212
 
212
213
 
213
214
  def _read_saved_result(
214
- scan_dir: Path, relative: str, scan_id: str, *, kind: str | None = None
215
+ scan_dir: Path,
216
+ relative: str,
217
+ scan_id: str,
218
+ *,
219
+ kind: str | None = None,
220
+ normalize_review: bool = True,
215
221
  ) -> tuple[dict[str, Any], str, int]:
216
222
  draft, _, metadata = _read_scan_local_json_with_metadata(
217
223
  scan_dir, relative, "Saved scan checkpoint"
@@ -237,10 +243,15 @@ def _read_saved_result(
237
243
  raise ContractError("checkpoint belongs to a different scan")
238
244
  if not _is_source_order_snapshot(relative) and (
239
245
  not isinstance(draft.get("findings"), list)
240
- or not isinstance(draft.get("coverage", {} if kind == "dedup" else None), dict)
246
+ or not isinstance(
247
+ draft.get("reviewState", draft.get("coverage", {} if kind == "dedup" else None)), dict
248
+ )
241
249
  ):
242
250
  raise ContractError("checkpoint has no semantic findings or coverage")
243
- return draft, _digest(draft), metadata.st_mtime_ns
251
+ digest = _digest(draft)
252
+ if normalize_review and "coverage" in draft and "reviewState" not in draft:
253
+ draft["reviewState"] = draft.pop("coverage")
254
+ return draft, digest, metadata.st_mtime_ns
244
255
 
245
256
 
246
257
  def _is_source_order_snapshot(relative: str) -> bool:
@@ -457,7 +468,10 @@ def _admit_parent_checkpoint(
457
468
  and "inputCheckpoint" in previous
458
469
  ):
459
470
  accepted, _, _ = _read_saved_result(
460
- scan_dir, f"checkpoints/{previous['inputCheckpoint']}", scan_id
471
+ scan_dir,
472
+ f"checkpoints/{previous['inputCheckpoint']}",
473
+ scan_id,
474
+ normalize_review=False,
461
475
  )
462
476
  if {key: value for key, value in accepted.items() if key != "publication"} == {
463
477
  key: value for key, value in checkpoint.items() if key != "publication"
@@ -527,7 +541,7 @@ def _parent_scan_draft(
527
541
  parent = {
528
542
  "scanId": scan_id,
529
543
  "findings": findings.get("findings"),
530
- "coverage": coverage,
544
+ "reviewState": coverage,
531
545
  **{
532
546
  key: parent_scan[key]
533
547
  for key in ("scope", "threatModel", "complete")
@@ -571,10 +585,14 @@ def _read_saved_parent_result(
571
585
  ) -> tuple[dict[str, Any], dict[str, Any]]:
572
586
  manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "Saved parent manifest")
573
587
  findings = _read_scan_local_json(scan_dir, "findings.json", "Saved parent findings")
574
- coverage = _read_scan_local_json(scan_dir, "coverage.json", "Saved parent coverage")
575
588
  parent_scan = manifest.get("scan")
576
589
  if not isinstance(parent_scan, dict):
577
590
  raise ContractError("Saved parent manifest has no scan object")
591
+ coverage = (
592
+ _read_scan_local_json(scan_dir, "coverage.json", "Saved parent coverage")
593
+ if uses_legacy_review(parent_scan)
594
+ else review_state(parent_scan)
595
+ )
578
596
  if manifest_is_sealed(parent_scan) and (
579
597
  parent_scan.get("id", scan_id) != scan_id
580
598
  or findings.get("scanId", scan_id) != scan_id
@@ -19,7 +19,6 @@ FINDING_CLOSE_REASONS = ("already_fixed", "wont_fix", "false_positive")
19
19
  REMEDIATION_UPDATE_STATES = ("generated", "applied", "verifying", "verified", "failed")
20
20
  EXPORT_FORMATS = ("csv", "json", "sarif")
21
21
  ARTIFACTS = {
22
- "coverage": "coverage.json",
23
22
  "findings": "findings.json",
24
23
  "manifest": "scan-manifest.json",
25
24
  "markdownReport": "report.md",
@@ -116,7 +116,7 @@ def retain_recorded_receipt_ownership(
116
116
  continue
117
117
  if payload_digest(draft) in recorded.get(directory, set()):
118
118
  continue
119
- surfaces = draft["coverage"].get("surfaces", [])
119
+ surfaces = draft["reviewState"].get("surfaces", [])
120
120
  for surface in surfaces if isinstance(surfaces, list) else []:
121
121
  if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
122
122
  surface["provenance"].pop("scanReceiptRefs", None)
@@ -240,7 +240,7 @@ def _generic_surface_updates(
240
240
 
241
241
  saved_surfaces: dict[tuple[str | None, str], list[tuple[str, dict[str, Any]]]] = {}
242
242
  for relative, draft, owner in sources:
243
- rows = draft["coverage"].get("surfaces", [])
243
+ rows = draft["reviewState"].get("surfaces", [])
244
244
  for row in rows if isinstance(rows, list) else []:
245
245
  if isinstance(row, dict) and isinstance(row.get("id"), str):
246
246
  saved_surfaces.setdefault(record_key("surfaces", owner, row), []).append(
@@ -270,7 +270,7 @@ def _generic_surface_updates(
270
270
  == record_order(latest_source, key[0], latest_surface)
271
271
  )
272
272
  for relative, draft, owner in sources:
273
- rows = draft["coverage"].get("surfaces", [])
273
+ rows = draft["reviewState"].get("surfaces", [])
274
274
  for row in rows if isinstance(rows, list) else []:
275
275
  if (
276
276
  isinstance(row, dict)
@@ -296,7 +296,7 @@ def _generic_surface_updates(
296
296
  normalized = _require_portable_relative_path(ref, "Saved coverage receipt")
297
297
  receipt_paths.setdefault(normalized.lower(), normalized)
298
298
  for relative, draft, owner in sources:
299
- current = draft["coverage"].get("surfaces", [])
299
+ current = draft["reviewState"].get("surfaces", [])
300
300
  for surface in current if isinstance(current, list) else []:
301
301
  if not isinstance(surface, dict):
302
302
  continue