← Files Codex SecurityARCHIVED FILE
scripts/workbench_coverage_receipts.py
20.8 KB · Nov 18, 2026 · 06:11 UTC
"""Resolve accepted worker receipt references without changing their ownership."""
from __future__ import annotations
import copy
import os
from collections.abc import Callable, Sequence
from pathlib import Path, PurePosixPath
from typing import Any
from finalize_scan_contract import (
ContractError,
MissingScanLocalFileError,
_require_portable_relative_path,
_require_str,
_validate_schema_node,
open_scan_local_file_descriptor,
path_within_scope,
)
from workbench.saved_coverage import _project_worker_coverage_row, _saved_coverage_id
def capture_receipt_checkpoints(
relative: str,
kind: str | None,
captured: dict[str, tuple[str, int]],
checkpoint_paths: Callable[[str], list[str]],
read_checkpoint: Callable[[str], tuple[dict[str, Any], str, int]],
) -> dict[str, tuple[str, int]]:
"""Bind a captured worker result to checkpoints visible after reading it."""
if kind == "discovery" and Path(relative).name == "result.json":
directory = (Path(relative).parent / "checkpoints").as_posix()
for path in checkpoint_paths(directory):
try:
_, digest, observed = read_checkpoint(path)
except (ContractError, OSError, ValueError):
continue
captured[path] = (digest, observed)
return captured
def receipt_checkpoints(
relative: str,
worker_id: str | None,
known: dict[str, str | None],
checkpoint_paths: Callable[[str], list[str]],
) -> dict[str, str]:
"""Capture host checkpoints written after enumeration but before result.json."""
if worker_id is None or Path(relative).name != "result.json":
return {}
directory = (Path(relative).parent / "checkpoints").as_posix()
added = {path: worker_id for path in checkpoint_paths(directory) if path not in known}
known.update(added)
return added
def retain_recorded_receipt_ownership(
sources: list[tuple[str, dict[str, Any], str | None]],
digest: Callable[[Any], str],
include_paths: Sequence[str],
finding_scope: Sequence[tuple[str, bool]] | None = None,
) -> None:
# Checkpoints are written by the host tool; direct result files can be authored
# without it. Compare the entire payload within the same worker attempt.
def payload_digest(draft: dict[str, Any]) -> str:
return digest({key: value for key, value in draft.items() if key != "handoffClaimToken"})
scope = (
finding_scope if finding_scope is not None else [(path, False) for path in include_paths]
)
recorded: dict[Path, set[str]] = {}
for relative, draft, worker_id in sources:
directory = Path(relative).parent
if worker_id is not None and directory.name == "checkpoints":
payloads = recorded.setdefault(directory.parent, set())
payloads.add(payload_digest(draft))
if "." not in include_paths:
# Legacy writers saved the checkpoint before filtering inherited findings.
scoped = [
finding
for finding in draft["findings"]
if isinstance(finding, dict)
and isinstance(finding.get("locations"), list)
and any(
isinstance(location, dict)
and isinstance(location.get("path"), str)
and any(
PurePosixPath(location["path"]) == PurePosixPath(path)
if is_file
else path_within_scope(location["path"], path)
for path, is_file in scope
)
for location in finding["locations"]
)
]
payloads.add(payload_digest({**draft, "findings": scoped}))
for relative, draft, worker_id in sources:
directory = Path(relative).parent
if worker_id is None or directory.name == "checkpoints":
continue
if payload_digest(draft) in recorded.get(directory, set()):
continue
surfaces = draft["reviewState"].get("surfaces", [])
for surface in surfaces if isinstance(surfaces, list) else []:
if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
surface["provenance"].pop("scanReceiptRefs", None)
def resolve_coverage_receipts(
scan_dir: Path, item: dict[str, Any], worker: Any, relative: str
) -> Any:
"""Qualify worker receipt references relative to their source checkpoint for use in parent coverage."""
refs = item.get("receiptRefs", [])
if not isinstance(refs, list):
return refs
directory = Path(relative).parent
if directory.name == "checkpoints":
directory = directory.parent
output = Path(worker["artifact_dir"]).relative_to(scan_dir)
worker_prefix = (output.parent if output.name == "output" else output).as_posix() + "/"
active_prefix = output.as_posix() + "/"
if directory != output:
refs = [
f"{directory.as_posix()}/{Path(ref).as_posix()[len(active_prefix) :]}"
if isinstance(ref, str) and Path(ref).as_posix().startswith(active_prefix)
else ref
for ref in refs
]
def scan_receipt(ref: str) -> bool:
try:
descriptor = open_scan_local_file_descriptor(scan_dir, ref, "coverage receipt")
except (ContractError, OSError):
return False
os.close(descriptor)
return True
def qualified_receipt(ref: Any) -> Any:
if not isinstance(ref, str):
return ref
try:
normalized = _require_portable_relative_path(ref, "Worker coverage receipt")
except ContractError:
return ref # Leave malformed references to per-record recovery.
if not normalized.startswith("artifacts/"):
# A worker prefix must not make result.json a valid coverage receipt.
return ref
ref = normalized
provenance = item.get("provenance")
inherited_scan_refs = (
provenance.get("scanReceiptRefs", []) if isinstance(provenance, dict) else []
)
if ref.startswith(worker_prefix) or (
isinstance(inherited_scan_refs, list) and ref in inherited_scan_refs
):
return ref
local_ref = Path(f"{directory}/{ref}").as_posix()
return local_ref if scan_receipt(local_ref) or not scan_receipt(ref) else ref
return [qualified_receipt(ref) for ref in refs]
def _deferred_candidate_id(
row: dict[str, Any],
owner: str | None,
ambiguous_deferred: set[tuple[str | None, str]],
) -> str | None:
identity = row.get("candidateId") or row.get("id")
if not isinstance(identity, str):
return None
if (owner, identity) in ambiguous_deferred and not any(
key in row for key in ("candidateId", "candidate", "finding")
):
return None
return identity
def _generic_surface_updates(
sources: list[tuple[str, dict[str, Any], str | None]],
closed_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]],
active_deferred: dict[tuple[str | None, str], tuple[tuple[int, int], dict[str, Any], str]],
resolved_candidates: dict[tuple[str | None, str], str],
reopened_generic: set[tuple[str | None, str]],
surface_schema: dict[str, Any],
deferred_rows: dict[str, list[Any]],
ambiguous_deferred: set[tuple[str | None, str]],
record_source: Any,
record_order: Any,
surface_receipts: Any,
*,
canonical_rows: set[int] | None = None,
coverage_sources: dict[int, tuple[dict[str, Any], list[str]]] | None = None,
surface_is_retained: Any = None,
eligible_receipt_sources: set[str] | None = None,
receipt_root: Path | None = None,
receipt_warnings: list[str] | None = None,
fallback_surfaces: list[dict[str, Any]] | None = None,
) -> tuple[set[int], list[tuple[str, str | None, dict[str, Any], dict[str, Any]]]]:
if not closed_deferred and not reopened_generic and receipt_root is None:
return set(), []
def receipt_error(ref: Any) -> ContractError | None:
if receipt_root is None or not isinstance(ref, str):
return ContractError("Saved coverage receipt is unavailable.")
try:
descriptor = open_scan_local_file_descriptor(
receipt_root, ref, "Saved coverage receipt"
)
os.close(descriptor)
except ContractError as exc:
return exc
return None
def record_key(field: str, owner: str | None, row: dict[str, Any]) -> tuple[str | None, Any]:
source_owner, original = record_source(field, owner, row)
identity = original.get("id")
return source_owner, identity if isinstance(identity, str) else None
def linked(row: dict[str, Any], identity: str | None, owner: str | None) -> bool:
_, row = record_source("deferred", owner, row)
surface_ids = row.get("surfaceIds", [])
return identity is not None and (
row.get("id") == identity or (isinstance(surface_ids, list) and identity in surface_ids)
)
saved_surfaces: dict[tuple[str | None, str], list[tuple[str, dict[str, Any]]]] = {}
for relative, draft, owner in sources:
rows = draft["reviewState"].get("surfaces", [])
for row in rows if isinstance(rows, list) else []:
if isinstance(row, dict) and isinstance(row.get("id"), str):
saved_surfaces.setdefault(record_key("surfaces", owner, row), []).append(
(relative, row)
)
replaced: set[int] = set()
updates: list[tuple[str, str | None, dict[str, Any], dict[str, Any]]] = []
# Current selections across all surfaces take precedence over historical refs.
receipt_paths: dict[str, str] = {}
retained_surfaces: dict[tuple[str | None, str], dict[str, Any]] = {}
if receipt_root is not None:
receipt_surfaces: list[tuple[str | None, dict[str, Any]]] = []
for key, matches in saved_surfaces.items():
retained = [
match for match in matches if surface_is_retained(match[0], key[0], match[1])
]
if not retained:
continue
latest_source, latest_surface = max(
retained, key=lambda match: record_order(match[0], key[0], match[1])
)
retained_surfaces[key] = latest_surface
receipt_surfaces.extend(
(key[0], row)
for relative, row in retained
if record_order(relative, key[0], row)
== record_order(latest_source, key[0], latest_surface)
)
for relative, draft, owner in sources:
rows = draft["reviewState"].get("surfaces", [])
for row in rows if isinstance(rows, list) else []:
if (
isinstance(row, dict)
and "id" not in row
and surface_is_retained(relative, owner, row)
):
receipt_surfaces.append((owner, row))
receipt_surfaces.extend((None, row) for row in fallback_surfaces or [])
for owner, latest_surface in receipt_surfaces:
# Recovery repairs disposition and receipts before validating row
# metadata. A row discarded there cannot reserve a receipt spelling.
metadata = _project_worker_coverage_row(latest_surface, owner, "surfaces")
metadata.setdefault("id", _saved_coverage_id(metadata))
metadata.update(disposition="needs_follow_up", receiptRefs=[])
try:
_require_str(metadata, "id", "coverage.surfaces")
_validate_schema_node(metadata, surface_schema, "coverage.surfaces")
except ContractError:
continue
refs = latest_surface.get("receiptRefs", [])
for ref in refs if isinstance(refs, list) else []:
if receipt_error(ref) is None:
normalized = _require_portable_relative_path(ref, "Saved coverage receipt")
receipt_paths.setdefault(normalized.lower(), normalized)
for relative, draft, owner in sources:
current = draft["reviewState"].get("surfaces", [])
for surface in current if isinstance(current, list) else []:
if not isinstance(surface, dict):
continue
surface_owner, identity = record_key("surfaces", owner, surface)
closed_ids = {
identity
for (saved_owner, identity), (_, _, source) in closed_deferred.items()
if saved_owner == surface_owner and source == relative
}
reopened_ids = {
identity
for (saved_owner, identity), (_, _, source) in active_deferred.items()
if saved_owner == surface_owner
and source == relative
and (owner, identity) in reopened_generic
}
reopening = surface.get("disposition") == "needs_follow_up"
work_ids = reopened_ids if reopening else closed_ids
repair_only = not work_ids
if repair_only and receipt_root is None:
continue
if not isinstance(identity, str):
continue
matches = saved_surfaces[(surface_owner, identity)]
# Receipt repair alone cannot close or reopen a saved surface.
if repair_only and any(
row.get("disposition") != surface.get("disposition") for _, row in matches
):
continue
# Older writers could assign one ID to distinct surfaces in a draft.
# A closure cannot identify which of those observations it replaces.
by_source = dict(matches)
if any(row != by_source[saved_path] for saved_path, row in matches):
continue
if any(
"candidateId" in row or "candidate" in row or "finding" in row for _, row in matches
):
continue
if any(
row is not surface
and record_order(saved_path, surface_owner, row)
>= record_order(relative, surface_owner, surface)
and row.get("disposition") != surface.get("disposition")
for saved_path, row in matches
):
continue
if not reopening and any(
saved_owner == surface_owner
and (
not isinstance(row.get("id") or row.get("candidateId"), str)
or (
isinstance(row.get("id"), str)
and (owner, row["id"]) in ambiguous_deferred
and not any(key in row for key in ("candidateId", "candidate", "finding"))
)
)
and linked(row, identity, saved_owner)
for saved_path, _, saved_owner in sources
for row in deferred_rows[saved_path]
if isinstance(row, dict)
):
continue
if not reopening and any(
saved_owner == surface_owner
and (owner, deferred_id) not in closed_deferred
and (
(candidate_id := _deferred_candidate_id(row, owner, ambiguous_deferred)) is None
or (owner, candidate_id) not in resolved_candidates
)
and linked(row, identity, saved_owner)
for (saved_owner, deferred_id), (_, row, _) in active_deferred.items()
):
continue
# An accepted checkpoint can update a saved surface by ID without
# optional surfaceIds links on its generic task.
receipt_matches = [
(saved_path, row)
for saved_path, row in matches
if receipt_root is None
or saved_path in eligible_receipt_sources
or surface_is_retained(saved_path, owner, row)
]
if not receipt_matches:
continue
latest_relative, latest_surface = max(
receipt_matches, key=lambda match: record_order(match[0], surface_owner, match[1])
)
target = (
retained_surfaces.get((surface_owner, identity)) if repair_only else latest_surface
)
if target is None:
continue
update = copy.deepcopy(target)
# Historical evidence can repair a retained row without promoting
# an unselected observation's label, notes, or other metadata.
refs = copy.deepcopy(surface_receipts(latest_relative, latest_surface))
update["receiptRefs"] = refs
replaced_receipt = False
replacement_paths = dict(receipt_paths)
if isinstance(refs, list):
repaired = (
not reopening and bool(refs) and all(receipt_error(ref) is None for ref in refs)
)
if repaired:
for ref in refs:
normalized = _require_portable_relative_path(ref, "Saved coverage receipt")
key = normalized.lower()
if key in replacement_paths and replacement_paths[key] != normalized:
repaired = False
break
replacement_paths[key] = normalized
for saved_relative, row in receipt_matches:
previous_refs = surface_receipts(saved_relative, row)
for ref in previous_refs if isinstance(previous_refs, list) else []:
if ref not in refs:
failure = receipt_error(ref) if repaired else None
replaceable = isinstance(failure, MissingScanLocalFileError)
if repaired and isinstance(ref, str):
try:
normalized = _require_portable_relative_path(
ref, "Saved coverage receipt"
)
except ContractError as error:
failure = error
replaceable = True
else:
key = normalized.lower()
previous = replacement_paths.get(key)
if previous is not None and previous != normalized:
failure = ContractError(
f"Saved coverage receipt: duplicate artifact path: {previous} and {normalized}"
)
replaceable = True
elif not replaceable:
replacement_paths[key] = normalized
if replaceable:
replaced_receipt = True
if receipt_warnings is not None:
receipt_warnings.append(
f"Replaced invalid saved coverage receipt {ref}: {failure}"
)
continue
refs.append(ref)
if repair_only and not replaced_receipt:
continue
try:
_validate_schema_node(update, surface_schema, "coverage.surfaces")
except ContractError:
continue
replaced_sources = {
id(row)
for _, row in matches
if reopening
or row.get("disposition") in {"needs_follow_up", surface.get("disposition")}
}
replaced.update(replaced_sources)
entry = (latest_relative, surface_owner, latest_surface, update)
if entry not in updates:
receipt_paths.update(replacement_paths)
updates.append(entry)
retained = next(
entry[3]
for entry in updates
if entry[:3] == (latest_relative, surface_owner, latest_surface)
and entry[3] == update
)
if coverage_sources is not None:
from workbench.retained_coverage import _inherit_coverage_sources
_inherit_coverage_sources(
retained,
[latest_surface, *(row for _, row in matches if id(row) in replaced_sources)],
coverage_sources,
)
if canonical_rows is not None and id(latest_surface) in canonical_rows:
canonical_rows.add(id(retained))
return replaced, updates
SHA-256: ab88ee90de1ff4607f9599607f76f0c619d4d5067b52a84d745b4c896703ee5a