← Files Codex SecurityARCHIVED FILE

scripts/finalize_scan_contract.py

144 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

#!/usr/bin/env python3
"""Validate and seal additive Codex Security scan-contract artifacts."""

from __future__ import annotations

import argparse
import copy
import csv
import errno
import hashlib
import io
import ipaddress
import json
import math
import os
import re
import stat
import struct
import sys
from collections.abc import Callable, Iterator
from contextlib import contextmanager
from datetime import datetime, timezone
from pathlib import Path, PurePosixPath
from typing import Any, NamedTuple, TextIO
from urllib.parse import quote, urlsplit

# Keep sibling helpers importable when Python starts in isolated mode.
sys.path.insert(0, str(Path(__file__).resolve().parent))
import report_projection
import servicenow_avit
import threat_model_projection
from legacy_findings import (
    _legacy_sealed_findings_for_validation,
    _normalize_legacy_string_list_fields,
)
from posix_scan_local_files import (
    descriptor_relative_writes_available as _descriptor_relative_writes_available,
)
from posix_scan_local_files import managed_fd, stage_write
from review_state import checkpoint_review_state, review_state, review_summary

SCHEMA_VERSION = "1.0"
PRODUCER_NAME = "codex-security-plugin"
FINGERPRINT_ALGORITHM = "codex-security/v1"
SARIF_SCHEMA = "https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/schemas/sarif-schema-2.1.0.json"
SEVERITIES = {"critical", "high", "medium", "low", "informational"}
CONFIDENCES = {"high", "medium", "low"}
TARGET_KINDS = {"git_revision", "git_worktree", "git_diff", "directory_snapshot"}
TARGET_COORDINATE_FIELDS = {
    "revision",
    "baseRevision",
    "headRevision",
    "snapshotDigest",
}
TARGET_REQUIRED_COORDINATE_FIELDS = {
    "git_revision": {"revision"},
    "git_worktree": {"snapshotDigest"},
    "git_diff": {"snapshotDigest"},
    "directory_snapshot": {"snapshotDigest"},
}
DISPOSITIONS = {"reported", "no_issue_found", "rejected", "not_applicable", "needs_follow_up"}
SARIF_LEVELS = {
    "critical": "error",
    "high": "error",
    "medium": "warning",
    "low": "note",
    "informational": "note",
}
SARIF_SECURITY_SCORES = {
    "critical": 9.5,
    "high": 8.0,
    "medium": 5.0,
    "low": 2.0,
    "informational": 0.0,
}
SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9._/-]*$")
RFC3339_RE = re.compile(
    r"^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.(?P<fraction>\d+))?(?:[Zz]|[+-]\d{2}:\d{2})$",
    re.ASCII,
)
REMOTE_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f-\x9f\u2028\u2029]")
REMOTE_UNSAFE_HOST_RE = re.compile(r"[\s<>^|]")
GITHUB_HASH_BLOCK_SIZE = 100
GITHUB_HASH_MOD = 37
GITHUB_HASH_MASK = (1 << 64) - 1
GITHUB_HASH_EOF = 65535
SOURCE_READ_CHUNK_SIZE = 64 * 1024
MAX_JSON_INTEGER = (1 << 53) - 1
EXPORT_PATHS = {
    "csv": "exports/findings.csv",
    "servicenow-avit": "exports/servicenow-avit.csv",
    "json": "exports/findings.json",
    "sarif": "exports/results.sarif",
}
THREAT_MODEL_EXPORT_PATH = "exports/threatmodel.md"
_LEGACY_THREAT_MODEL_PATHS = (
    "threatmodel.md",
    "THREAT_MODEL.md",
    "artifacts/01_context/threat_model.md",
    "threat_model.md",
)
WINDOWS_UNSAFE_PATH_COMPONENT_RE = re.compile(
    r'[<>:"|?*\x00-\x1f]|[ .]$|^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?:\..*)?$',
    re.IGNORECASE,
)


class ContractError(ValueError):
    """Raised when a completed scan does not satisfy the additive contract."""


class ScanLocalIOError(ContractError):
    """Raised when scan-local storage I/O fails, distinct from path validation."""


class MissingScanLocalFileError(ContractError):
    """Raised when a scan-local file or its containing directory is absent."""


class RecoverableContractError(ContractError):
    """Raised when scan completion can safely be retried before publication."""


class SealedArtifactError(ContractError):
    """Raised when an export would overwrite a sealed scan artifact."""


def _reject_non_finite_json(value: str) -> None:
    raise ValueError(f"non-finite JSON number {value!r} is not supported")


def _loads_json(value: str | bytes) -> Any:
    return json.loads(value, parse_constant=_reject_non_finite_json)


def _read_json(path: Path) -> dict[str, Any]:
    try:
        payload = _loads_json(path.read_text(encoding="utf-8"))
        _require_safe_json_value(payload, str(path))
    except FileNotFoundError as exc:
        raise ContractError(f"missing required contract artifact: {path}") from exc
    except ContractError:
        raise
    except ValueError as exc:
        raise ContractError(f"{path}: invalid JSON: {exc}") from exc
    if not isinstance(payload, dict):
        raise ContractError(f"{path}: expected a JSON object")
    return payload


def _generate_report_projection(
    manifest: dict[str, Any],
    findings: dict[str, Any],
    coverage: dict[str, Any],
) -> bytes:
    try:
        return report_projection.generate_report_markdown(manifest, findings, coverage)
    except ValueError as exc:
        raise ContractError(f"report projection failed: {exc}") from exc


def threat_model_provenance(manifest: dict[str, Any]) -> dict[str, Any]:
    if manifest.get("documentType") == "codex-security.policy-draft":
        scope = manifest.get("scope")
        return {
            "source": "policy",
            "target": manifest.get("repository"),
            "revision": manifest.get("revision"),
            "scanScope": {"includePaths": [scope], "excludePaths": []} if scope else None,
            "status": manifest.get("status", "completed"),
            "provisional": manifest.get("status", "completed") != "completed",
        }
    scan = _require_dict(manifest, "scan", "manifest")
    target = _require_dict(scan, "target", "manifest.scan") if "target" in scan else {}
    status = scan.get("status")
    if status == "completed" and not scan.get("sealedAt"):
        status = "draft"
    return {
        "source": "scan",
        "scanId": scan.get("id"),
        "target": target.get("displayName"),
        "revision": target.get("revision") or target.get("headRevision"),
        "snapshotDigest": target.get("snapshotDigest"),
        "scanScope": scan.get("scope"),
        "status": status,
        "provisional": scan.get("status") != "completed" or not scan.get("sealedAt"),
    }


def _render_threat_model(model: dict[str, Any], provenance: dict[str, Any]) -> bytes:
    try:
        return threat_model_projection.render_threat_model(model, provenance)
    except (TypeError, ValueError) as exc:
        raise ContractError(f"threat model projection failed: {exc}") from exc


def _read_saved_threat_model(
    scan_dir: Path, *, validate_seal: bool = True, schema_dir: Path | None = None
) -> tuple[dict[str, Any], bytes] | None:
    """Read canonical content first; old documents are a read-only compatibility path."""
    scan_dir = _require_scan_directory(scan_dir)
    saved_provenance: dict[str, Any] | None = None
    sealed_artifact_paths: set[str] | None = None
    scan_manifest_path = scan_dir / "scan-manifest.json"
    filename = (
        "scan-manifest.json"
        if scan_manifest_path.exists() or scan_manifest_path.is_symlink()
        else "policy-draft.json"
    )
    manifest_path = scan_dir / filename
    if manifest_path.exists() or manifest_path.is_symlink():
        manifest = _read_scan_local_json(scan_dir, filename, filename)
        scan = (
            _require_dict(manifest, "scan", "manifest")
            if filename == "scan-manifest.json"
            else manifest
        )
        if validate_seal and filename == "scan-manifest.json" and manifest_is_sealed(scan):
            if "threatModel" not in scan:
                _validate_manifest(manifest)
                recorded_paths = {
                    _require_portable_relative_path(artifact["path"], "sealed artifact path")
                    for artifact in scan["artifacts"]
                }
                if recorded_paths.isdisjoint(_LEGACY_THREAT_MODEL_PATHS):
                    validate_against_schema(
                        manifest,
                        (schema_dir or Path(__file__).resolve().parent.parent / "schemas")
                        / "scan-manifest.schema.json",
                    )
                    return None
            manifest, _, _, _ = _read_sealed_scan(scan_dir, schema_dir, "threat model export")
            scan = manifest["scan"]
            sealed_artifact_paths = {
                _require_portable_relative_path(artifact["path"], "sealed artifact path")
                for artifact in scan["artifacts"]
            }
        provenance = threat_model_provenance(manifest)
        saved_provenance = provenance
        if "threatModel" in scan:
            model = _require_dict(
                scan,
                "threatModel",
                "manifest.scan" if filename == "scan-manifest.json" else "policy draft",
            )
            contents = _render_threat_model(model, provenance)
            path = scan_dir / "threatmodel.md"
            current_path = None
            try:
                descriptor = open_scan_local_file_descriptor(
                    scan_dir, "threatmodel.md", "Saved threat model"
                )
                with os.fdopen(descriptor, "rb") as handle:
                    if handle.read() == contents:
                        current_path = str(path)
            except (ContractError, OSError):
                # An unavailable projection does not invalidate the canonical model.
                pass
            return {
                "threatModel": model,
                "provenance": provenance,
                "path": current_path,
            }, contents
    for filename in _LEGACY_THREAT_MODEL_PATHS:
        if sealed_artifact_paths is not None and filename not in sealed_artifact_paths:
            continue
        path = scan_dir / filename
        if not path.exists() and not path.is_symlink():
            continue
        descriptor, filename = _open_scan_local_file_with_path(
            scan_dir,
            filename,
            "Saved threat model",
            resolve_spelling=sealed_artifact_paths is None,
        )
        path = scan_dir / filename
        with os.fdopen(descriptor, "rb") as handle:
            contents = handle.read()
        try:
            body = contents.decode("utf-8")
        except UnicodeDecodeError as exc:
            raise ContractError(f"{filename}: expected UTF-8 Markdown") from exc
        if body.strip():
            return {
                "threatModel": {"format": "markdown", "content": body},
                "provenance": saved_provenance
                or {"source": filename, "status": "unknown", "provisional": True},
                "path": str(path),
            }, contents
    return None


def describe_threat_model(scan_dir: Path, schema_dir: Path | None = None) -> dict[str, Any]:
    saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
    if saved is None:
        raise ContractError("No saved threat model is available for this result.")
    return saved[0]


def build_threat_model_export(scan_dir: Path, schema_dir: Path | None = None) -> bytes:
    saved = _read_saved_threat_model(scan_dir, schema_dir=schema_dir)
    if saved is None:
        raise ContractError("No saved threat model is available for this result.")
    return saved[1]


def write_threat_model_projection_if_possible(
    scan_dir: Path, manifest: dict[str, Any] | None = None
) -> str | None:
    """A convenience document failure must not discard saved canonical content."""
    try:
        saved_manifest = manifest
        if saved_manifest is None and (scan_dir / "scan-manifest.json").exists():
            saved_manifest = _read_scan_local_json(
                scan_dir, "scan-manifest.json", "scan-manifest.json"
            )
        if (
            saved_manifest is not None
            and saved_manifest.get("documentType") != "codex-security.policy-draft"
        ):
            scan = _require_dict(saved_manifest, "scan", "manifest")
            artifacts = (
                _require_list(scan, "artifacts", "manifest.scan") if "artifacts" in scan else []
            )
            for index, artifact in enumerate(artifacts):
                if not isinstance(artifact, dict):
                    continue
                context = f"manifest.scan.artifacts[{index}]"
                path = _require_portable_relative_path(
                    _require_str(artifact, "path", context), f"{context}.path"
                )
                if path.lower() == "threatmodel.md":
                    return None
        if manifest is None:
            saved = _read_saved_threat_model(scan_dir, validate_seal=False)
            if saved is None:
                return None
            contents = saved[1]
        else:
            scan = (
                manifest
                if manifest.get("documentType") == "codex-security.policy-draft"
                else _require_dict(manifest, "scan", "manifest")
            )
            model = scan.get("threatModel")
            if not isinstance(model, dict):
                return None
            contents = _render_threat_model(model, threat_model_provenance(manifest))
        write_scan_local_bytes(scan_dir, "threatmodel.md", contents, owner_read_write=True)
        return None
    except (ContractError, OSError) as exc:
        warning = (
            f"Automatic threat model save failed: {exc}. "
            "Saved canonical content can be exported with `codex-security export "
            "<result-dir> --artifact threat-model`."
        )
        print(f"codex-security: warning: {warning}", file=sys.stderr)
        return warning


def _json_bytes(payload: Any) -> bytes:
    try:
        encoded = json.dumps(payload, allow_nan=False, indent=2, sort_keys=True)
    except ValueError as exc:
        raise ContractError(f"cannot encode canonical JSON: {exc}") from exc
    return (encoded + "\n").encode("utf-8")


def _contract_json_bytes(relative_path: str, payload: Any) -> bytes:
    _require_safe_json_value(payload, relative_path)
    return _json_bytes(payload)


def _require_safe_json_value(value: Any, context: str, *, validate_strings: bool = True) -> None:
    def visit(item: Any, location: str) -> None:
        if isinstance(item, dict):
            for key, child in item.items():
                if not isinstance(key, str):
                    raise ContractError(f"{location}: expected string JSON property names")
                if validate_strings:
                    _require_safe_json_string(key, location)
                visit(child, f"{location}.<property>")
        elif isinstance(item, list):
            for index, child in enumerate(item):
                visit(child, f"{location}[{index}]")
        elif isinstance(item, str) and validate_strings:
            _require_safe_json_string(item, location)
        elif isinstance(item, int) and not isinstance(item, bool):
            if abs(item) > MAX_JSON_INTEGER:
                raise ContractError(
                    f"{location}: unsafe integer-valued JSON numbers are not supported"
                )
        elif isinstance(item, float):
            if not math.isfinite(item):
                raise ContractError(f"{location}: non-finite JSON numbers are not supported")
            if item.is_integer() and abs(item) > MAX_JSON_INTEGER:
                raise ContractError(
                    f"{location}: unsafe integer-valued JSON numbers are not supported"
                )

    visit(value, context)


def _require_safe_json_string(value: str, context: str) -> None:
    try:
        value.encode("utf-8")
    except UnicodeEncodeError as exc:
        raise ContractError(f"{context}: expected well-formed Unicode JSON strings") from exc


def _require_dict(payload: dict[str, Any], key: str, context: str) -> dict[str, Any]:
    value = payload.get(key)
    if not isinstance(value, dict):
        raise ContractError(f"{context}.{key}: expected an object")
    return value


def _require_list(payload: dict[str, Any], key: str, context: str) -> list[Any]:
    value = payload.get(key)
    if not isinstance(value, list):
        raise ContractError(f"{context}.{key}: expected an array")
    return value


def _require_str(payload: dict[str, Any], key: str, context: str) -> str:
    value = payload.get(key)
    if not isinstance(value, str) or not value.strip():
        raise ContractError(f"{context}.{key}: expected a non-empty string")
    return value


def _require_safe_relative_path(value: object, context: str, *, allow_dot: bool = False) -> str:
    if not isinstance(value, str) or not value:
        raise ContractError(f"{context}: expected a safe repository-relative POSIX path")
    try:
        value.encode("utf-8")
    except UnicodeEncodeError as exc:
        raise ContractError(f"{context}: expected a safe repository-relative POSIX path") from exc
    path = PurePosixPath(value)
    normalized = path.as_posix()
    if (
        (normalized == "." and not allow_dot)
        or re.match(r"^[A-Za-z]:", value)
        or "\\" in value
        or "\0" in value
        or any(ord(character) < 32 for character in value)
        or path.is_absolute()
        or ".." in path.parts
    ):
        raise ContractError(f"{context}: expected a safe repository-relative POSIX path")
    return normalized


def _require_portable_relative_path(value: str, context: str, *, allow_dot: bool = False) -> str:
    normalized = _require_safe_relative_path(value, context, allow_dot=allow_dot)
    if not value.strip() or any(_windows_unsafe_path_component(part) for part in value.split("/")):
        raise ContractError(f"{context}: expected a safe scan-relative POSIX path")
    return normalized


def _windows_unsafe_path_component(value: str) -> bool:
    if not value or value == ".":
        return False
    return WINDOWS_UNSAFE_PATH_COMPONENT_RE.search(value) is not None


def _scan_local_directory_error(message: str, error: OSError) -> ContractError:
    if error.errno in {errno.ENOENT, errno.ENOTDIR, errno.ELOOP}:
        return ContractError(message)
    return ScanLocalIOError(message)


def _require_scan_directory(scan_dir: Path, context: str = "scan directory") -> Path:
    scan_dir = scan_dir.absolute()
    try:
        metadata = scan_dir.lstat()
    except OSError as exc:
        raise _scan_local_directory_error(
            f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
        ) from exc
    if not stat.S_ISDIR(metadata.st_mode):
        raise ContractError(f"{context}: expected an existing non-symlink directory")
    try:
        resolved = scan_dir.resolve(strict=True)
    except OSError as exc:
        raise _scan_local_directory_error(
            f"{context} {scan_dir}: expected an existing non-symlink directory: {exc}", exc
        ) from exc
    if os.path.normcase(resolved) != os.path.normcase(scan_dir):
        raise ContractError(f"{context}: expected a canonical non-symlink directory")
    return resolved


def _validate_scan_local_output_path(scan_dir: Path, path: Path, relative_path: str) -> None:
    try:
        resolved_parent = path.parent.resolve(strict=True)
        resolved_parent.relative_to(scan_dir)
    except (OSError, RuntimeError, ValueError) as exc:
        raise ContractError(f"{relative_path}: expected a path inside the scan directory") from exc
    if os.path.normcase(resolved_parent) != os.path.normcase(path.parent) or path.is_symlink():
        raise ContractError(
            f"{relative_path}: expected a non-symlink path inside the scan directory"
        )
    if path.exists() and not path.is_file():
        raise ContractError(f"{relative_path}: expected a regular file")


def _is_windows() -> bool:
    return os.name == "nt"


def _windows_scan_local_files() -> Any:
    """Load the Win32 backend and shared stream comparison lazily."""
    import windows_scan_local_files

    return windows_scan_local_files


def _open_verified_scan_directory(
    scan_dir: Path, expected_root_identity: tuple[int, int] | None = None
) -> int:
    scan_dir = scan_dir.absolute()
    try:
        expected = scan_dir.lstat()
        observed_identity = (expected.st_dev, expected.st_ino)
        if expected_root_identity is not None and observed_identity != expected_root_identity:
            raise ContractError("scan directory: changed after artifact restoration setup")
        canonical = _require_scan_directory(scan_dir)
        descriptor = os.open(
            canonical,
            os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
        )
    except OSError as exc:
        raise _scan_local_directory_error(
            "scan directory: expected an existing non-symlink directory", exc
        ) from exc
    try:
        if not os.path.samestat(expected, os.fstat(descriptor)):
            raise ContractError("scan directory: changed while it was being opened")
    except BaseException:
        os.close(descriptor)
        raise
    return descriptor


def scan_root_identity(scan_dir: Path) -> tuple[Path, tuple[int, int]]:
    """Return a canonical scan root and its identity from a held handle."""

    scan_dir = _require_scan_directory(scan_dir)
    if not _descriptor_relative_writes_available():
        if not _is_windows():
            raise ContractError("scan-local output requires descriptor-relative file operations")
        return _windows_scan_local_files().scan_root_identity(scan_dir)
    descriptor = _open_verified_scan_directory(scan_dir)
    try:
        metadata = os.fstat(descriptor)
        return scan_dir, (metadata.st_dev, metadata.st_ino)
    finally:
        os.close(descriptor)


def _open_scan_local_directory(
    root_fd: int,
    parts: tuple[str, ...],
    *,
    create: bool,
    owner_read_write: bool = False,
    sync_parents: bool = False,
) -> int:
    descriptor = os.dup(root_fd)
    try:
        for part in parts:
            if sync_parents:
                os.fsync(descriptor)
            if create:
                try:
                    os.mkdir(part, mode=0o700, dir_fd=descriptor)
                except FileExistsError:
                    # The open below verifies that an existing entry is a real directory.
                    pass
                else:
                    if owner_read_write:
                        mode = os.stat(part, dir_fd=descriptor, follow_symlinks=False).st_mode
                        if mode & stat.S_IRWXU != stat.S_IRWXU:
                            os.rmdir(part, dir_fd=descriptor)
                            raise ScanLocalIOError(
                                f"{part}: process umask prevents owner access to the new directory"
                            )
            parent_descriptor = descriptor
            descriptor = os.open(
                part,
                os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
                dir_fd=parent_descriptor,
            )
            # If closing the parent fails, cleanup now owns the child.
            os.close(parent_descriptor)
        return descriptor
    except BaseException:
        os.close(descriptor)
        raise


def open_scan_local_file_descriptor(
    scan_dir: Path, relative_path: str, context: str, *, portable: bool = True
) -> int:
    return _open_scan_local_file_with_path(scan_dir, relative_path, context, portable=portable)[0]


def _open_scan_local_file_with_path(
    scan_dir: Path,
    relative_path: str,
    context: str,
    *,
    resolve_spelling: bool = False,
    portable: bool = True,
) -> tuple[int, str]:
    scan_dir = _require_scan_directory(scan_dir)
    validate_path = _require_portable_relative_path if portable else _require_safe_relative_path
    relative_path = validate_path(relative_path, context)
    if not (os.open in os.supports_dir_fd and hasattr(os, "O_NOFOLLOW")):
        if not _is_windows():
            raise ContractError("scan-local input requires descriptor-relative file operations")
        try:
            backend = _windows_scan_local_files()
            if resolve_spelling:
                return backend.open_read_fd_with_path(scan_dir, relative_path, context)
            return backend.open_read_fd(scan_dir, relative_path, context), relative_path
        except OSError as exc:
            # The Windows backend retains native ERROR_FILE/PATH_NOT_FOUND codes.
            if exc.errno in {2, 3}:
                raise MissingScanLocalFileError(
                    f"{context}: expected a file inside the scan directory"
                ) from exc
            raise ContractError(str(exc)) from exc
    root_fd: int | None = None
    parent_fd: int | None = None
    descriptor: int | None = None
    try:
        root_fd = _open_verified_scan_directory(scan_dir)
        parts = PurePosixPath(relative_path).parts
        try:
            parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=False)
            descriptor = os.open(
                parts[-1],
                os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_NONBLOCK", 0),
                dir_fd=parent_fd,
            )
        except OSError as exc:
            if exc.errno == errno.ENOENT:
                raise MissingScanLocalFileError(
                    f"{context}: expected a file inside the scan directory"
                ) from exc
            if exc.errno == errno.ELOOP:
                try:
                    link_target = Path(os.readlink(parts[-1], dir_fd=parent_fd))
                    if not link_target.is_absolute():
                        link_target = scan_dir.joinpath(*parts[:-1], link_target)
                    link_target.resolve(strict=False).relative_to(scan_dir)
                except (OSError, RuntimeError, ValueError):
                    raise ContractError(
                        f"{context}: expected a file inside the scan directory"
                    ) from exc
                raise ContractError(f"{context}: expected a regular non-symlink file") from exc
            raise ContractError(f"{context}: expected a file inside the scan directory") from exc
        metadata = os.fstat(descriptor)
        if not stat.S_ISREG(metadata.st_mode):
            raise ContractError(f"{context}: expected a regular non-symlink file")
        if resolve_spelling:
            names = os.listdir(parent_fd)
            if parts[-1] not in names:
                for name in names:
                    if name.casefold() != parts[-1].casefold():
                        continue
                    try:
                        entry = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
                    except FileNotFoundError:
                        continue
                    if os.path.samestat(metadata, entry):
                        relative_path = PurePosixPath(relative_path).with_name(name).as_posix()
                        break
        result = descriptor
        descriptor = None
        return result, relative_path
    finally:
        if descriptor is not None:
            os.close(descriptor)
        if parent_fd is not None:
            os.close(parent_fd)
        if root_fd is not None:
            os.close(root_fd)


def _require_scan_local_file(scan_dir: Path, relative_path: str, context: str) -> None:
    descriptor = open_scan_local_file_descriptor(scan_dir, relative_path, context)
    os.close(descriptor)


def _prepare_derived_writeups(
    scan_dir: Path,
    findings: dict[str, Any],
    *,
    allow_missing: bool = False,
) -> list[str]:
    warnings: list[str] = []
    for index, finding in enumerate(findings.get("findings", [])):
        if not isinstance(finding, dict):
            continue
        writeup = finding.get("writeup")
        if not isinstance(writeup, dict):
            continue
        report_path = writeup.get("reportPath")
        if isinstance(report_path, str):
            try:
                _require_scan_local_file(
                    scan_dir,
                    report_path,
                    f"findings[{index}].writeup.reportPath",
                )
            except MissingScanLocalFileError as exc:
                if not allow_missing:
                    raise
                finding.pop("writeup")
                warnings.append(f"Skipped missing writeup for finding {index + 1}: {exc}.")
    return warnings


def _require_hardening_portfolio_file(scan_dir: Path, scan: dict[str, Any]) -> None:
    hardening = scan.get("hardening")
    if not isinstance(hardening, dict):
        return
    portfolio_path = hardening.get("portfolioPath")
    if isinstance(portfolio_path, str):
        _require_scan_local_file(
            scan_dir,
            portfolio_path,
            "manifest.scan.hardening.portfolioPath",
        )


def _read_scan_local_json_with_metadata(
    scan_dir: Path, relative_path: str, context: str
) -> tuple[dict[str, Any], bytes, os.stat_result]:
    descriptor = open_scan_local_file_descriptor(scan_dir, relative_path, context)
    try:
        with os.fdopen(descriptor, "rb") as handle:
            descriptor = -1
            raw = handle.read()
            metadata = os.fstat(handle.fileno())
        try:
            payload = _loads_json(raw.decode("utf-8-sig"))
        except (UnicodeDecodeError, ValueError) as exc:
            raise ContractError(f"{context}: invalid JSON: {exc}") from exc
        if not isinstance(payload, dict):
            raise ContractError(f"{context}: expected a JSON object")
        _require_safe_json_value(payload, context, validate_strings=False)
    finally:
        if descriptor >= 0:
            os.close(descriptor)
    return payload, raw, metadata


def _read_scan_local_json_bytes(
    scan_dir: Path, relative_path: str, context: str
) -> tuple[dict[str, Any], bytes]:
    payload, raw, _ = _read_scan_local_json_with_metadata(scan_dir, relative_path, context)
    return payload, raw


def _read_scan_local_json(scan_dir: Path, relative_path: str, context: str) -> dict[str, Any]:
    payload, _ = _read_scan_local_json_bytes(scan_dir, relative_path, context)
    return payload


def _sha256_scan_local_file(scan_dir: Path, relative_path: str, context: str) -> str:
    descriptor = open_scan_local_file_descriptor(scan_dir, relative_path, context)
    digest = hashlib.sha256()
    try:
        with os.fdopen(descriptor, "rb") as handle:
            descriptor = -1
            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
                digest.update(chunk)
    finally:
        if descriptor >= 0:
            os.close(descriptor)
    return digest.hexdigest()


def scan_local_file_version(descriptor: int) -> tuple[os.stat_result, int]:
    metadata = os.fstat(descriptor)
    changed = (
        _windows_scan_local_files().file_change_time(descriptor)
        if _is_windows()
        else metadata.st_ctime_ns
    )
    return metadata, changed


def _scan_local_write_path(
    scan_dir: Path, relative_path: str, external_name: bool
) -> tuple[Path, str]:
    scan_dir = _require_scan_directory(
        scan_dir, "export output directory" if external_name else "scan directory"
    )
    if external_name:
        if relative_path in {"", ".", ".."} or "/" in relative_path or "\0" in relative_path:
            raise ContractError("external output path: expected a safe file name")
    else:
        relative_path = _require_portable_relative_path(relative_path, "scan-local output path")
    return scan_dir, relative_path


@contextmanager
def _windows_write_errors(backend: Any, relative_path: str) -> Iterator[None]:
    try:
        yield
    except FileExistsError:
        raise
    except backend.WindowsScanLocalPathError as exc:
        raise ContractError(f"{relative_path}: {exc}") from exc
    except OSError as exc:
        raise ScanLocalIOError(f"{relative_path}: {exc}") from exc


def write_scan_local_bytes(
    scan_dir: Path,
    relative_path: str,
    payload: bytes,
    *,
    external_name: bool = False,
    expected_root_identity: tuple[int, int] | None = None,
    owner_read_write: bool = False,
    replace_existing: bool = True,
) -> None:
    if _is_windows() and not _descriptor_relative_writes_available():
        scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
        backend = _windows_scan_local_files()
        with _windows_write_errors(backend, relative_path):
            backend.atomic_write(
                scan_dir,
                relative_path,
                payload,
                expected_root_identity=expected_root_identity,
                replace_existing=replace_existing,
            )
        return
    with stage_scan_local_bytes(
        scan_dir,
        relative_path,
        payload,
        external_name=external_name,
        expected_root_identity=expected_root_identity,
        owner_read_write=owner_read_write,
        replace_existing=replace_existing,
    ) as publish:
        publish()


@contextmanager
def stage_scan_local_bytes(
    scan_dir: Path,
    relative_path: str,
    payload: bytes,
    *,
    external_name: bool = False,
    expected_root_identity: tuple[int, int] | None = None,
    owner_read_write: bool = False,
    replace_existing: bool = False,
) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
    """Stage payload under the scan directory and yield a callback that publishes it.

    Call the callback inside the context to get file metadata and a platform-specific
    change-time token. Leaving without publishing discards the staged write.
    """
    scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
    if not _descriptor_relative_writes_available():
        if not _is_windows():
            raise ContractError("scan-local output requires descriptor-relative file operations")
        backend = _windows_scan_local_files()
        with _windows_write_errors(backend, relative_path):
            with backend.stage_write(
                scan_dir,
                relative_path,
                payload,
                expected_root_identity=expected_root_identity,
                replace_existing=replace_existing,
            ) as publish:
                yield publish
        return
    with managed_fd(_open_verified_scan_directory(scan_dir, expected_root_identity)) as root_fd:
        parts = PurePosixPath(relative_path).parts
        try:
            parent_fd = _open_scan_local_directory(
                root_fd, parts[:-1], create=True, owner_read_write=owner_read_write
            )
        except OSError as exc:
            raise _scan_local_directory_error(
                f"{relative_path}: expected a path inside the scan directory", exc
            ) from exc

        with managed_fd(parent_fd):

            def check_parent(directory: Path) -> None:
                # Admission can follow an archive while the staged parent stays open.
                root = os.fstat(root_fd)
                with (
                    managed_fd(
                        _open_verified_scan_directory(directory, (root.st_dev, root.st_ino))
                    ) as current,
                    managed_fd(
                        _open_scan_local_directory(current, parts[:-1], create=False)
                    ) as parent,
                ):
                    if not os.path.samestat(os.fstat(parent_fd), os.fstat(parent)):
                        raise ContractError(f"{relative_path}: parent changed before publication")

            with stage_write(
                parent_fd,
                relative_path,
                payload,
                owner_read_write=owner_read_write,
                replace_existing=replace_existing,
                compare_existing=expected_root_identity is not None,
                check_parent=check_parent,
                contract_error=ContractError,
            ) as publish:
                yield publish


def _remove_scan_local_file_if_exists(scan_dir: Path, relative_path: str) -> None:
    scan_dir = _require_scan_directory(scan_dir)
    relative_path = _require_portable_relative_path(relative_path, "scan-local cleanup path")
    if not _descriptor_relative_writes_available():
        if not _is_windows():
            raise ContractError("scan-local cleanup requires descriptor-relative file operations")
        try:
            _windows_scan_local_files().unlink_if_exists(scan_dir, relative_path)
        except OSError as exc:
            raise ContractError(f"{relative_path}: {exc}") from exc
        return
    root_fd: int | None = None
    parent_fd: int | None = None
    try:
        root_fd = _open_verified_scan_directory(scan_dir)
        parts = PurePosixPath(relative_path).parts
        parent_fd = _open_scan_local_directory(root_fd, parts[:-1], create=False)
        try:
            metadata = os.stat(parts[-1], dir_fd=parent_fd, follow_symlinks=False)
        except FileNotFoundError:
            return
        if not (stat.S_ISREG(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode)):
            raise ContractError(f"{relative_path}: expected a regular file or symlink")
        os.unlink(parts[-1], dir_fd=parent_fd)
    finally:
        if parent_fd is not None:
            os.close(parent_fd)
        if root_fd is not None:
            os.close(root_fd)


def _write_scan_local_json(scan_dir: Path, relative_path: str, payload: Any) -> None:
    write_scan_local_bytes(scan_dir, relative_path, _contract_json_bytes(relative_path, payload))


def _validate_remote(remote: str, context: str) -> None:
    if REMOTE_CONTROL_RE.search(remote):
        raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
    try:
        parsed = urlsplit(remote)
    except ValueError as exc:
        # urlsplit rejects authorities with unbalanced brackets.
        raise ContractError(
            f"{context}: expected a sanitized canonical absolute URL: {exc}"
        ) from exc
    if "\\" in remote or not parsed.scheme or not parsed.netloc:
        raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
    if "@" in parsed.netloc or parsed.query or parsed.fragment:
        raise ContractError(
            f"{context}: remote URL must not contain credentials, query, or fragment"
        )
    # Mirrors the authority rules of the WHATWG URL parser the SDK reader applies.
    authority = parsed.netloc
    if authority.startswith("["):
        try:
            ipaddress.IPv6Address(authority.partition("]")[0][1:])
        except ValueError as exc:
            raise ContractError(f"{context}: expected a sanitized canonical absolute URL") from exc
        authority = authority.partition("]")[2]
        if authority and not authority.startswith(":"):
            raise ContractError(f"{context}: expected a sanitized canonical absolute URL")
    port = authority.partition(":")[2]
    hostname = parsed.hostname
    if (
        not hostname
        or REMOTE_UNSAFE_HOST_RE.search(hostname)
        or (port and (not port.isascii() or not port.isdigit() or int(port) > 65535))
    ):
        raise ContractError(f"{context}: expected a sanitized canonical absolute URL")


def parse_timestamp(value: str) -> datetime:
    match = RFC3339_RE.fullmatch(value)
    if match and (fraction := match.group("fraction")):
        start, end = match.span("fraction")
        value = value[:start] + fraction[:6].ljust(6, "0") + value[end:]
    return datetime.fromisoformat(value.upper().replace("Z", "+00:00"))


def _validate_date_time(value: str, context: str) -> None:
    if not RFC3339_RE.fullmatch(value):
        raise ContractError(f"{context}: expected an RFC 3339 timestamp")
    try:
        parsed = parse_timestamp(value)
    except ValueError as exc:
        raise ContractError(f"{context}: expected an RFC 3339 timestamp") from exc
    if parsed.tzinfo is None:
        raise ContractError(f"{context}: expected an RFC 3339 timestamp")


def _validate_target(target: dict[str, Any]) -> None:
    kind = _require_str(target, "kind", "scan.target")
    if kind not in TARGET_KINDS:
        raise ContractError(f"scan.target.kind: unsupported target kind: {kind}")
    _require_str(target, "targetId", "scan.target")
    _require_str(target, "displayName", "scan.target")
    remote = target.get("remote")
    if remote is not None:
        if not isinstance(remote, str):
            raise ContractError("scan.target.remote: expected a string")
        _validate_remote(remote, "scan.target.remote")
    if kind == "git_revision":
        _require_str(target, "revision", "scan.target")
    elif kind in ("git_worktree", "git_diff", "directory_snapshot"):
        _require_str(target, "snapshotDigest", "scan.target")


def _fingerprint(target_id: str, finding: dict[str, Any]) -> str:
    identity = _require_dict(finding, "identity", "finding")
    anchor = _require_str(identity, "anchor", "finding.identity")
    if not SLUG_RE.fullmatch(anchor):
        raise ContractError("finding.identity.anchor: expected a stable lowercase semantic slug")
    instance = identity.get("instance", "")
    if not isinstance(instance, str):
        raise ContractError("finding.identity.instance: expected a string")
    if instance and not SLUG_RE.fullmatch(instance):
        raise ContractError("finding.identity.instance: expected a stable lowercase semantic slug")
    rule_id = _require_str(finding, "ruleId", "finding")
    if not SLUG_RE.fullmatch(rule_id):
        raise ContractError("finding.ruleId: expected a stable lowercase rule slug")
    material = "\0".join((FINGERPRINT_ALGORITHM, target_id, rule_id, anchor, instance))
    return f"{FINGERPRINT_ALGORITHM}:sha256:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"


def _stable_id(prefix: str, *parts: str) -> str:
    return f"{prefix}_{hashlib.sha256(chr(0).join(parts).encode('utf-8')).hexdigest()[:24]}"


def _validate_location(location: dict[str, Any], context: str) -> None:
    _require_safe_relative_path(location.get("path"), f"{context}.path")
    start = location.get("startLine")
    end = location.get("endLine", start)
    if not isinstance(start, int) or start < 1:
        raise ContractError(f"{context}.startLine: expected a positive integer")
    if not isinstance(end, int) or end < start:
        raise ContractError(f"{context}.endLine: expected an integer >= startLine")
    role = location.get("role")
    if role is not None and (not isinstance(role, str) or not role):
        raise ContractError(f"{context}.role: expected a non-empty string")


def _derived_finding_identity_rows(
    manifest: dict[str, Any],
    findings: dict[str, Any],
) -> list[tuple[str, dict[str, Any], str, str, dict[str, str]]]:
    scan = _require_dict(manifest, "scan", "manifest")
    scan_id = _require_str(scan, "id", "manifest.scan")
    target_id = _require_str(
        _require_dict(scan, "target", "manifest.scan"), "targetId", "scan.target"
    )
    if findings.get("scanId") != scan_id:
        raise ContractError("findings.scanId: must match manifest scan id")

    finding_ids: set[str] = set()
    occurrence_ids: set[str] = set()
    rows: list[tuple[str, dict[str, Any], str, str, dict[str, str]]] = []
    for index, finding in enumerate(_require_list(findings, "findings", "findings")):
        context = f"findings.findings[{index}]"
        if not isinstance(finding, dict):
            raise ContractError(f"{context}: expected an object")
        fingerprint = _fingerprint(target_id, finding)
        expected_finding_id = _stable_id("csf", fingerprint)
        expected_occurrence_id = _stable_id("occ", scan_id, fingerprint)
        expected_fingerprints = {"algorithm": FINGERPRINT_ALGORITHM, "primary": fingerprint}
        rows.append(
            (
                context,
                finding,
                expected_finding_id,
                expected_occurrence_id,
                expected_fingerprints,
            )
        )
        finding_ids.add(expected_finding_id)
        if expected_occurrence_id in occurrence_ids:
            raise ContractError(
                f"{context}: duplicate occurrence identity; use identity.instance to split siblings"
            )
        occurrence_ids.add(expected_occurrence_id)

    if len(finding_ids) != len(occurrence_ids):
        raise ContractError("findings: duplicate logical findings in one scan")
    return rows


def _populate_unsealed_finding_identities(
    manifest: dict[str, Any],
    findings: dict[str, Any],
) -> None:
    """Replace draft-owned finding identities with deterministic finalizer values."""

    for _, finding, finding_id, occurrence_id, fingerprints in _derived_finding_identity_rows(
        manifest,
        findings,
    ):
        finding["findingId"] = finding_id
        finding["occurrenceId"] = occurrence_id
        finding["fingerprints"] = fingerprints


def _finding_strength(finding: dict[str, Any]) -> tuple[int, int, int]:
    return (
        ("informational", "low", "medium", "high", "critical").index(finding["severity"]["level"]),
        ("low", "medium", "high").index(finding["confidence"]["level"]),
        _finding_evidence_strength(finding),
    )


def _recover_code_evidence(
    finding: dict[str, Any],
    item_schema: dict[str, Any],
    context: str,
    warnings: list[str],
) -> dict[str, Any]:
    evidence = finding["codeEvidence"]
    # Validate before the legacy adapter resolves references and deduplicates IDs.
    by_id: dict[str, dict[str, Any] | None] = {}
    if isinstance(evidence, list):
        for index, row in enumerate(evidence):
            location = f"{context}.codeEvidence[{index}]"
            try:
                _validate_schema_node(row, item_schema, location)
                _require_safe_json_value(row, location)
                _require_str(row, "code", location)
                _require_safe_relative_path(row["path"], f"{location}.path")
                evidence_id = row["id"]
                if evidence_id in by_id:
                    if not _schema_values_equal(by_id[evidence_id], row):
                        # Conflicting sources cannot both identify one evidence row.
                        by_id[evidence_id] = None
                    raise ContractError(f"{location}.id: duplicate code-evidence id")
                by_id[evidence_id] = row
            except ContractError as exc:
                warnings.append(f"Skipped malformed codeEvidence: {exc}.")
        rows = [row for row in by_id.values() if row is not None]
        if len(rows) == len(evidence):
            return finding
    else:
        warnings.append(
            f"Skipped malformed codeEvidence: {context}.codeEvidence: expected an array."
        )
        rows = []
    repaired = finding.copy()
    if rows:
        repaired["codeEvidence"] = rows
    else:
        repaired.pop("codeEvidence")
    return repaired


def _recover_unsealed_findings(
    manifest: dict[str, Any],
    findings: dict[str, Any],
    schema_dir: Path,
    scan_dir: Path,
    warnings: list[str],
    *,
    current_contract: bool = False,
) -> list[str]:
    schema = _read_json(schema_dir / "findings.schema.json")
    properties = _require_dict(schema, "properties", "findings.schema")
    finding_array = _require_dict(properties, "findings", "findings.schema.properties")
    finding_schema = _require_dict(finding_array, "items", "findings.schema.properties.findings")
    finding_properties = _require_dict(
        finding_schema, "properties", "findings.schema.properties.findings.items"
    )
    writeup_schema = _require_dict(
        finding_properties, "writeup", "findings.schema.properties.findings.items.properties"
    )
    auxiliary_schemas = {
        name: _require_dict(
            finding_properties, name, "findings.schema.properties.findings.items.properties"
        )
        for name in ("remediationTests", "preventiveControls")
    }
    scan = _require_dict(manifest, "scan", "manifest")
    scan_id = _require_str(scan, "id", "manifest.scan")
    if findings.get("scanId") != scan_id:
        raise ContractError("findings.scanId: must match manifest scan id")

    recovered: list[dict[str, Any]] = []
    discarded: list[str] = []
    finding_positions: dict[str, int] = {}
    writeup_paths: set[str] = set()
    evidence_schema = None
    for index, finding in enumerate(_require_list(findings, "findings", "findings")):
        context = f"findings.findings[{index}]"
        evidence_warnings: list[str] = []
        try:
            if not isinstance(finding, dict):
                raise ContractError(f"{context}: expected an object")
            if "codeEvidence" in finding:
                if evidence_schema is None:
                    evidence_schema = (
                        _current_finding_definition(schema_dir, "codeEvidence")
                        if current_contract
                        else finding_properties["codeEvidence"]["items"]
                    )
                finding = _recover_code_evidence(
                    finding, evidence_schema, context, evidence_warnings
                )
            compatible_findings = _legacy_sealed_findings_for_validation({"findings": [finding]})[
                "findings"
            ]
            compatible_finding = compatible_findings[0]
            normalized_legacy_details = compatible_finding != finding
            finding = compatible_finding
            identity = _require_dict(finding, "identity", context)
            fields: list[tuple[dict[str, Any], str, str, str]] = [
                (finding, "ruleId", context, "rule identifier"),
                (identity, "anchor", f"{context}.identity", "semantic anchor"),
            ]
            if "instance" in identity:
                fields.append((identity, "instance", f"{context}.identity", "instance"))
            normalized_fields = ["legacy finding details"] if normalized_legacy_details else []
            taxonomy = finding.get("taxonomy")
            if isinstance(taxonomy, dict) and "cwe" not in taxonomy:
                taxonomy["cwe"] = []
                normalized_fields.append("missing taxonomy.cwe to an empty list")
            for parent, field, field_context, label in fields:
                value = _require_str(parent, field, field_context)
                if SLUG_RE.fullmatch(value):
                    continue
                normalized = re.sub(r"[^a-z0-9._/-]+", "-", value.lower()).strip("._/-")
                if not SLUG_RE.fullmatch(normalized):
                    raise ContractError(
                        f"{field_context}.{field}: expected a stable lowercase semantic slug"
                    )
                parent[field] = normalized
                normalized_fields.append(label)

            severity = finding.get("severity")
            if isinstance(severity, dict):
                change_conditions = severity.get("changeConditions")
                if (
                    isinstance(change_conditions, list)
                    and change_conditions
                    and all(
                        isinstance(condition, str) and condition.strip()
                        for condition in change_conditions
                    )
                ):
                    for condition_index, condition in enumerate(change_conditions):
                        _require_safe_json_string(
                            condition,
                            f"{context}.severity.changeConditions[{condition_index}]",
                        )
                    severity["changeConditions"] = " ".join(
                        condition.strip() for condition in change_conditions
                    )
                    normalized_fields.append("severity change conditions")

            _populate_unsealed_finding_identities(
                manifest,
                {"scanId": scan_id, "findings": [finding]},
            )
            finding_id = finding["findingId"]
            previous_position = finding_positions.get(finding_id)
            _validate_finding(finding, context)
            if "writeup" in finding:
                try:
                    _validate_schema_node(finding["writeup"], writeup_schema, f"{context}.writeup")
                    report_path = finding["writeup"]["reportPath"]
                    previous_writeup = (
                        recovered[previous_position].get("writeup")
                        if previous_position is not None
                        else None
                    )
                    if report_path in writeup_paths and (
                        previous_writeup is None or previous_writeup["reportPath"] != report_path
                    ):
                        raise ContractError(f"{context}.writeup.reportPath: duplicate report path")
                    _require_scan_local_file(scan_dir, report_path, f"{context}.writeup.reportPath")
                except ContractError as exc:
                    finding.pop("writeup")
                    warnings.append(f"Skipped malformed writeup for finding {index + 1}: {exc}.")
            for auxiliary, auxiliary_schema in auxiliary_schemas.items():
                if auxiliary not in finding:
                    continue
                try:
                    _validate_schema_node(
                        finding[auxiliary], auxiliary_schema, f"{context}.{auxiliary}", schema
                    )
                except ContractError as exc:
                    finding.pop(auxiliary)
                    warnings.append(
                        f"Skipped malformed {auxiliary} for finding {index + 1}: {exc}."
                    )
            _validate_schema_node(finding, finding_schema, context, schema)
            _require_safe_json_value(finding, context)
            if current_contract:
                _validate_current_findings({"findings": [finding]}, schema_dir)
        except ContractError as exc:
            warning = f"Skipped malformed finding {index + 1}: {exc}."
            warnings.append(warning)
            discarded.append(warning)
            continue

        if previous_position is not None:
            previous = recovered[previous_position]
            strongest, earlier = (
                (previous, finding)
                if _finding_strength(finding) <= _finding_strength(previous)
                else (finding, previous)
            )
            if strongest != earlier:
                original = copy.deepcopy(earlier)
                older = original["provenance"].pop("previousFindings", [])
                if not isinstance(strongest["provenance"].get("previousFindings"), list):
                    strongest["provenance"]["previousFindings"] = []
                history = strongest["provenance"]["previousFindings"]
                for record in [*(older if isinstance(older, list) else []), original]:
                    if record not in history:
                        history.append(record)
            if _finding_strength(finding) <= _finding_strength(previous):
                warnings.append(
                    f"Skipped malformed finding {index + 1}: duplicate logical finding."
                )
                continue
            previous_writeup = previous.get("writeup")
            if previous_writeup is not None:
                writeup_paths.discard(previous_writeup["reportPath"])
            recovered[previous_position] = finding
            warnings.append(
                f"Recovered finding {index + 1}: retained stronger duplicate logical finding."
            )
        else:
            finding_positions[finding_id] = len(recovered)
            recovered.append(finding)

        if "writeup" in finding:
            writeup_paths.add(finding["writeup"]["reportPath"])
        warnings.extend(evidence_warnings)
        if normalized_fields:
            warnings.append(
                f"Recovered finding {index + 1}: normalized {', '.join(normalized_fields)}."
            )

    findings["findings"] = recovered
    return discarded


def _recover_unsealed_coverage(
    coverage: dict[str, Any],
    schema_dir: Path,
    scan_dir: Path,
    warnings: list[str],
    discarded_findings: list[str],
    *,
    worker_draft: bool = False,
) -> set[str]:
    schema = _read_json(schema_dir / "coverage.schema.json")
    properties = _require_dict(schema, "properties", "coverage.schema")
    discarded_fields: set[str] = set()
    if (
        coverage.get("mode") == "deep_repository"
        and coverage.get("inventoryStrategy") != "repository"
    ):
        coverage["inventoryStrategy"] = "repository"
        warnings.append("Recovered malformed Deep Scan inventory strategy.")

    surface_ids: set[str] = set()
    receipt_paths: dict[str, str] = {}
    fields = [
        ("surfaces", "coverage surface"),
        ("explicitExclusions", "coverage exclusion"),
        ("deferred", "deferred coverage item"),
    ]
    if worker_draft:
        if "openQuestions" in coverage:
            _normalize_unsealed_open_questions(coverage)
            fields.append(("openQuestions", "coverage open question"))
        if "resolvedDeferred" in coverage:
            fields.append(("resolvedDeferred", "resolved deferred item"))
    for field, label in fields:
        array_schema = _require_dict(properties, field, "coverage.schema.properties")
        item_schema = _require_dict(array_schema, "items", f"coverage.schema.properties.{field}")
        items = coverage.get(field)
        if not isinstance(items, list):
            warnings.append(f"Skipped malformed {label} records: expected an array.")
            discarded_fields.add(field)
            coverage[field] = []
            continue

        recovered: list[dict[str, Any]] = []
        for index, item in enumerate(items):
            context = f"coverage.{field}[{index}]"
            try:
                if not isinstance(item, dict):
                    raise ContractError(f"{context}: expected an object")
                if field == "surfaces":
                    surface_receipt_paths = dict(receipt_paths)
                    surface_id = _require_str(item, "id", context)
                    if worker_draft:
                        _require_str(item, "label", context)
                    if surface_id in surface_ids and not worker_draft:
                        raise ContractError(f"{context}.id: duplicate surface id")
                    disposition = item.get("disposition")
                    surface_recovered = False
                    if not isinstance(disposition, str) or disposition not in DISPOSITIONS:
                        warnings.append(
                            f"Recovered coverage surface {index + 1}: "
                            "the review disposition could not be verified."
                        )
                        item["disposition"] = "needs_follow_up"
                        surface_recovered = True

                    receipt_refs = item.get("receiptRefs")
                    if not isinstance(receipt_refs, list):
                        warnings.append(
                            f"Skipped malformed receipt references for coverage surface "
                            f"{index + 1}: expected an array."
                        )
                        receipt_refs = []
                        surface_recovered = True

                    recovered_receipts: list[str] = []
                    for ref_index, ref in enumerate(receipt_refs):
                        ref_context = f"{context}.receiptRefs[{ref_index}]"
                        try:
                            if not isinstance(ref, str):
                                raise ContractError(f"{ref_context}: expected a string")
                            normalized_ref = _require_portable_relative_path(ref, ref_context)
                            if not normalized_ref.startswith("artifacts/"):
                                raise ContractError(
                                    f"{ref_context}: expected a file under artifacts/"
                                )
                            _require_scan_local_file(scan_dir, normalized_ref, ref_context)
                            key = normalized_ref.lower()
                            previous = surface_receipt_paths.get(key)
                            if previous is not None and previous != normalized_ref:
                                raise ContractError(f"{ref_context}: duplicate artifact path")
                            surface_receipt_paths[key] = normalized_ref
                        except ContractError as exc:
                            warnings.append(
                                f"Skipped malformed coverage receipt "
                                f"{index + 1}.{ref_index + 1}: {exc}."
                            )
                            surface_recovered = True
                            continue
                        recovered_receipts.append(normalized_ref)

                    item["receiptRefs"] = recovered_receipts
                    if surface_recovered:
                        item["disposition"] = "needs_follow_up"
                        discarded_fields.add(field)

                if field == "deferred":
                    _validate_deferred_paths(item, context)
                _validate_schema_node(item, item_schema, context)
                if field == "resolvedDeferred":
                    _validate_resolved_deferred({"resolvedDeferred": [item]})
                if worker_draft:
                    _require_safe_json_value(item, context)
            except ContractError as exc:
                warnings.append(f"Skipped malformed {label} {index + 1}: {exc}.")
                discarded_fields.add(field)
                continue

            if field == "surfaces":
                surface_ids.add(surface_id)
                receipt_paths = surface_receipt_paths
            recovered.append(item)

        coverage[field] = recovered

    if discarded_findings:
        for surface in coverage["surfaces"]:
            if (
                worker_draft
                and surface.get("candidateId")
                and surface["disposition"] in {"rejected", "not_applicable"}
            ):
                # A valid explicit outcome can still resolve that worker's history.
                continue
            surface["disposition"] = "needs_follow_up"
        coverage["deferred"].extend(
            {"id": f"discarded-finding-{index}", "reason": warning}
            for index, warning in enumerate(discarded_findings, 1)
        )

    if "resolvedDeferred" in coverage:
        try:
            _validate_schema_node(
                coverage["resolvedDeferred"],
                properties["resolvedDeferred"],
                "coverage.resolvedDeferred",
            )
            _validate_resolved_deferred(coverage)
            if worker_draft:
                _require_safe_json_value(coverage["resolvedDeferred"], "coverage.resolvedDeferred")
        except ContractError as exc:
            coverage.pop("resolvedDeferred")
            warnings.append(f"Skipped malformed resolved deferred work: {exc}.")
            discarded_fields.add("resolvedDeferred")
    return discarded_fields


def _recover_unsealed_hardening(
    manifest: dict[str, Any],
    scan_dir: Path,
    warnings: list[str],
) -> None:
    scan = _require_dict(manifest, "scan", "manifest")
    if "hardening" not in scan:
        return

    try:
        hardening = _require_dict(scan, "hardening", "manifest.scan")
        portfolio_path = _require_str(hardening, "portfolioPath", "manifest.scan.hardening")
        if portfolio_path != "hardening/hardening.md":
            raise ContractError(
                "manifest.scan.hardening.portfolioPath: expected hardening/hardening.md"
            )
        _require_hardening_portfolio_file(scan_dir, scan)
    except ContractError as exc:
        scan.pop("hardening")
        warnings.append(f"Skipped malformed hardening portfolio: {exc}.")


def _validate_derived_finding_identities(
    manifest: dict[str, Any],
    findings: dict[str, Any],
) -> None:
    """Require sealed finding identities to equal their deterministic values."""

    for context, finding, finding_id, occurrence_id, fingerprints in _derived_finding_identity_rows(
        manifest,
        findings,
    ):
        if finding.get("findingId") != finding_id:
            raise ContractError(f"{context}.findingId: does not match derived fingerprint identity")
        if finding.get("occurrenceId") != occurrence_id:
            raise ContractError(f"{context}.occurrenceId: does not match scan occurrence identity")
        if finding.get("fingerprints") != fingerprints:
            raise ContractError(f"{context}.fingerprints: does not match derived fingerprint")


def _populate_unsealed_manifest_envelope(
    manifest: dict[str, Any],
    scan: dict[str, Any],
    completion_binding: dict[str, Any] | None,
) -> None:
    """Populate non-semantic draft fields owned by finalization or the workbench."""

    manifest["documentType"] = "codex-security.scan-manifest"
    manifest["schemaVersion"] = SCHEMA_VERSION
    scan["status"] = (
        completion_binding.get("status", "completed") if completion_binding else "completed"
    )
    scan["findingsRef"] = "findings.json"
    if "coverageRef" in scan:
        scan["coverageRef"] = "coverage.json"
    if completion_binding is None:
        started_at = os.environ.get("CODEX_SECURITY_STARTED_AT")
        if started_at is not None:
            _validate_date_time(started_at, "CODEX_SECURITY_STARTED_AT")
            scan["startedAt"] = started_at
            scan["completedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
        return

    scan["id"] = completion_binding["scanId"]
    scan["startedAt"] = completion_binding["startedAt"]
    scan["completedAt"] = completion_binding["completedAt"]
    scan["producer"] = copy.deepcopy(completion_binding["producer"])

    target = scan.setdefault("target", {})
    if isinstance(target, dict):
        allowed_kinds = completion_binding["allowedTargetKinds"]
        if len(allowed_kinds) == 1:
            target.setdefault("kind", allowed_kinds[0])
        _populate_unsealed_target_binding(target, completion_binding["target"], allowed_kinds)

    scope = scan.setdefault("scope", {})
    if isinstance(scope, dict):
        scope.update(copy.deepcopy(completion_binding["scope"]))


def _populate_unsealed_target_kind(
    target: dict[str, Any],
    target_binding: dict[str, Any],
    allowed_kinds: Any,
) -> None:
    """Adopt the registered target kind when the binding owns every coordinate it needs.

    The workbench, not the draft, knows how the target was registered: a scan agent
    that infers the kind from the checkout (a clean worktree registered as
    git_revision is the common case) used to discard the whole completed scan at the
    seal step. The kind carries no draft-owned information when the registration
    allows a single value, so take that value instead of failing.

    Rewriting the kind also reinterprets the coordinates that kind requires, and a
    coordinate the binding does not own survives the replacement below with whatever
    the draft computed under its own reading of the target. Adopting git_diff without
    a bound snapshotDigest, for example, would seal a whole-worktree digest as the
    diff digest. Leave the kind alone whenever the binding cannot restate every
    coordinate the registered kind requires, and let the binding check reject the
    draft instead.
    """

    if not isinstance(allowed_kinds, list) or len(allowed_kinds) != 1:
        return
    registered_kind = allowed_kinds[0]
    if not isinstance(registered_kind, str) or target.get("kind") == registered_kind:
        return
    if not TARGET_REQUIRED_COORDINATE_FIELDS.get(registered_kind, set()) <= target_binding.keys():
        return
    target["kind"] = registered_kind


def _populate_unsealed_target_binding(
    target: dict[str, Any],
    target_binding: dict[str, Any],
    allowed_kinds: Any = None,
) -> None:
    """Replace workbench-owned target coordinates without retaining incompatible drafts."""

    _populate_unsealed_target_kind(target, target_binding, allowed_kinds)
    target_kind = target.get("kind")
    required_coordinates = (
        TARGET_REQUIRED_COORDINATE_FIELDS.get(target_kind, set())
        if isinstance(target_kind, str)
        else set()
    )
    for field in TARGET_COORDINATE_FIELDS:
        if field not in target_binding and field not in required_coordinates:
            target.pop(field, None)
    target.update(copy.deepcopy(target_binding))


def _populate_unsealed_artifact_envelope(
    manifest: dict[str, Any],
    findings: dict[str, Any],
    coverage: dict[str, Any],
    completion_binding: dict[str, Any] | None,
) -> None:
    """Populate deterministic top-level draft fields after refs have been resolved."""

    findings["documentType"] = "codex-security.findings"
    findings["schemaVersion"] = SCHEMA_VERSION
    coverage["documentType"] = "codex-security.coverage"
    coverage["schemaVersion"] = SCHEMA_VERSION
    if completion_binding is None:
        return

    scan_id = completion_binding["scanId"]
    findings["scanId"] = scan_id
    coverage["scanId"] = scan_id
    coverage["mode"] = completion_binding["coverageMode"]

    scan = _require_dict(manifest, "scan", "manifest")
    scope = _require_dict(scan, "scope", "manifest.scan")
    if "includePaths" in scope:
        coverage["includePaths"] = copy.deepcopy(scope["includePaths"])
    if "excludePaths" in scope:
        coverage["excludePaths"] = copy.deepcopy(scope["excludePaths"])


def _normalize_unsealed_open_questions(coverage: dict[str, Any]) -> None:
    """Keep only schema-valid optional open-question rows without inventing content."""

    open_questions = coverage.get("openQuestions")
    if not isinstance(open_questions, list):
        coverage.pop("openQuestions", None)
        return

    normalized: list[Any] = []
    for item in open_questions:
        if isinstance(item, str):
            question = item.strip()
            if question:
                normalized.append({"question": question})
            continue
        if not isinstance(item, dict):
            continue

        question = item.get("question")
        if not isinstance(question, str) or not question.strip():
            continue
        row = dict(item)
        row["question"] = question.strip()
        follow_up = row.get("followUpPrompt")
        if not isinstance(follow_up, str) or not follow_up.strip():
            row.pop("followUpPrompt", None)
        normalized.append(row)
    coverage["openQuestions"] = normalized


def _validate_completion_binding(
    manifest: dict[str, Any],
    findings: dict[str, Any],
    coverage: dict[str, Any],
    completion_binding: dict[str, Any] | None,
) -> None:
    """Verify populated workbench-owned fields before an unsealed draft is written."""

    if completion_binding is None:
        return
    scan = _require_dict(manifest, "scan", "manifest")
    if scan.get("id") != completion_binding["scanId"]:
        raise ContractError("manifest.scan.id: must match the workbench scan")
    if scan.get("status") != completion_binding.get("status", "completed"):
        raise ContractError("manifest.scan.status: must match the workbench outcome")
    if scan.get("startedAt") != completion_binding["startedAt"]:
        raise ContractError("manifest.scan.startedAt: must match the workbench scan")
    if scan.get("completedAt") != completion_binding["completedAt"]:
        raise ContractError("manifest.scan.completedAt: must match the workbench completion")
    if scan.get("producer") != completion_binding["producer"]:
        raise ContractError("manifest.scan.producer: must match the workbench producer")
    target = _require_dict(scan, "target", "manifest.scan")
    allowed_target_kinds = completion_binding["allowedTargetKinds"]
    if target.get("kind") not in allowed_target_kinds:
        raise ContractError("scan.target.kind: must match the workbench target")
    for key, expected in completion_binding["target"].items():
        if target.get(key) != expected:
            raise ContractError(f"scan.target.{key}: must match the workbench target")
    scope = _require_dict(scan, "scope", "manifest.scan")
    for key, expected in completion_binding["scope"].items():
        if scope.get(key) != expected:
            raise ContractError(f"manifest.scan.scope.{key}: must match the workbench scan")
    if findings.get("scanId") != completion_binding["scanId"]:
        raise ContractError("findings.scanId: must match the workbench scan")
    if coverage.get("scanId") != completion_binding["scanId"]:
        raise ContractError("coverage.scanId: must match the workbench scan")
    if coverage.get("mode") != completion_binding["coverageMode"]:
        raise ContractError("coverage.mode: must match the workbench scan")
    for key, expected in completion_binding["scope"].items():
        if coverage.get(key) != expected:
            raise ContractError(f"coverage.{key}: must match the workbench scan")


def path_within_scope(path: str, scope: str) -> bool:
    candidate = PurePosixPath(path)
    requested = PurePosixPath(scope)
    if candidate.is_absolute() or ".." in candidate.parts:
        return False
    return candidate.is_relative_to(requested)


def _validate_finding(finding: dict[str, Any], context: str) -> None:
    for key in ("findingId", "occurrenceId", "ruleId", "title", "summary", "remediation"):
        _require_str(finding, key, context)
    _require_dict(finding, "identity", context)
    fingerprints = _require_dict(finding, "fingerprints", context)
    if fingerprints.get("algorithm") != FINGERPRINT_ALGORITHM:
        raise ContractError(f"{context}.fingerprints.algorithm: unsupported algorithm")
    _require_str(fingerprints, "primary", f"{context}.fingerprints")

    severity = _require_dict(finding, "severity", context)
    level = _require_str(severity, "level", f"{context}.severity")
    if level not in SEVERITIES:
        raise ContractError(f"{context}.severity.level: unsupported severity: {level}")
    score = severity.get("score")
    if score is not None:
        if not isinstance(score, (int, float)) or isinstance(score, bool) or not 0 <= score <= 10:
            raise ContractError(f"{context}.severity.score: expected a number from 0 through 10")
        _require_str(severity, "scoringSystem", f"{context}.severity")

    confidence = _require_dict(finding, "confidence", context)
    confidence_level = _require_str(confidence, "level", f"{context}.confidence")
    if confidence_level not in CONFIDENCES:
        raise ContractError(
            f"{context}.confidence.level: unsupported confidence: {confidence_level}"
        )
    _require_str(confidence, "rationale", f"{context}.confidence")

    taxonomy = _require_dict(finding, "taxonomy", context)
    _require_str(taxonomy, "category", f"{context}.taxonomy")
    cwe = taxonomy.get("cwe", [])
    if not isinstance(cwe, list) or any(not isinstance(item, str) or not item for item in cwe):
        raise ContractError(f"{context}.taxonomy.cwe: expected an array of strings")

    locations = _require_list(finding, "locations", context)
    if not locations:
        raise ContractError(f"{context}.locations: expected at least one location")
    for index, location in enumerate(locations):
        if not isinstance(location, dict):
            raise ContractError(f"{context}.locations[{index}]: expected an object")
        _validate_location(location, f"{context}.locations[{index}]")

    evidence_ids: set[str] = set()
    for evidence_key in ("codeEvidence", "code_evidence"):
        if evidence_key not in finding:
            continue
        code_evidence = finding[evidence_key]
        if not isinstance(code_evidence, list):
            raise ContractError(f"{context}.{evidence_key}: expected an array")
        for index, evidence in enumerate(code_evidence):
            evidence_context = f"{context}.{evidence_key}[{index}]"
            if not isinstance(evidence, dict):
                raise ContractError(f"{evidence_context}: expected an object")
            evidence_id = _require_str(evidence, "id", evidence_context)
            if evidence_id in evidence_ids:
                raise ContractError(f"{evidence_context}.id: duplicate code-evidence id")
            evidence_ids.add(evidence_id)
            _require_str(evidence, "code", evidence_context)
            if evidence_key == "codeEvidence":
                _require_safe_relative_path(
                    evidence.get("path"),
                    f"{evidence_context}.path",
                )

    referenced_sections = [
        (section_name, finding.get(section_name))
        for section_name in ("rootCause", "root_cause", "validation", "attackPath")
    ]
    attack_path = finding.get("attackPath")
    if isinstance(attack_path, dict):
        referenced_sections.extend(
            (f"attackPath.{section_name}", attack_path.get(section_name))
            for section_name in ("dataFlow", "dataflow", "data_flow", "reachability")
        )
    for section_name, section in referenced_sections:
        if not isinstance(section, dict):
            continue
        for refs_key in ("evidenceRefs", "evidence_refs"):
            if refs_key not in section:
                continue
            refs = section[refs_key]
            if not isinstance(refs, list) or any(
                not isinstance(ref, str) or not ref for ref in refs
            ):
                raise ContractError(f"{context}.{section_name}.{refs_key}: expected strings")
            unknown_refs = sorted(set(refs) - evidence_ids)
            if unknown_refs:
                raise ContractError(
                    f"{context}.{section_name}.{refs_key}: unknown code-evidence ids: "
                    + ", ".join(unknown_refs)
                )

    provenance = _require_dict(finding, "provenance", context)
    _require_str(provenance, "source", f"{context}.provenance")
    extensions = finding.get("extensions")
    if extensions is not None and not isinstance(extensions, dict):
        raise ContractError(f"{context}.extensions: expected an object")


def _validate_resolved_deferred(coverage: dict[str, Any]) -> None:
    if "resolvedDeferred" not in coverage:
        return
    active = {
        identity
        for row in coverage.get("deferred", [])
        if isinstance(row, dict)
        for identity in (row.get("id"), row.get("candidateId"))
        if isinstance(identity, str)
    }
    resolved: set[str] = set()
    for index, closure in enumerate(_require_list(coverage, "resolvedDeferred", "coverage")):
        context = f"coverage.resolvedDeferred[{index}]"
        if not isinstance(closure, dict):
            raise ContractError(f"{context}: expected an object")
        closure_id = _require_str(closure, "id", context)
        _require_str(closure, "reason", context)
        if closure_id in resolved:
            raise ContractError(f"{context}.id: duplicate resolved deferred id")
        if closure_id in active:
            raise ContractError(f"{context}.id: deferred work is still active")
        resolved.add(closure_id)


def _validate_deferred_paths(deferred: dict[str, Any], context: str) -> None:
    if "paths" not in deferred:
        return
    for index, path in enumerate(_require_list(deferred, "paths", context)):
        if not isinstance(path, str):
            raise ContractError(f"{context}.paths[{index}]: expected a string")
        _require_safe_relative_path(path, f"{context}.paths[{index}]", allow_dot=True)


def _validate_coverage(manifest: dict[str, Any], coverage: dict[str, Any], scan_dir: Path) -> None:
    scan = _require_dict(manifest, "scan", "manifest")
    scan_id = _require_str(scan, "id", "manifest.scan")
    if coverage.get("scanId") != scan_id:
        raise ContractError("coverage.scanId: must match manifest scan id")
    _require_str(coverage, "mode", "coverage")
    _require_str(coverage, "inventoryStrategy", "coverage")
    scope = _require_dict(scan, "scope", "manifest.scan")
    if coverage.get("includePaths") != scope.get("includePaths"):
        raise ContractError("coverage.includePaths: must match manifest scope")
    if coverage.get("excludePaths") != scope.get("excludePaths"):
        raise ContractError("coverage.excludePaths: must match manifest scope")
    surface_ids: set[str] = set()
    for index, surface in enumerate(_require_list(coverage, "surfaces", "coverage")):
        context = f"coverage.surfaces[{index}]"
        if not isinstance(surface, dict):
            raise ContractError(f"{context}: expected an object")
        surface_id = _require_str(surface, "id", context)
        if surface_id in surface_ids:
            raise ContractError(f"{context}.id: duplicate surface id")
        surface_ids.add(surface_id)
        _require_str(surface, "label", context)
        disposition = _require_str(surface, "disposition", context)
        if disposition not in DISPOSITIONS:
            raise ContractError(f"{context}.disposition: unsupported disposition: {disposition}")
        receipt_refs = surface.get("receiptRefs", [])
        if not isinstance(receipt_refs, list):
            raise ContractError(f"{context}.receiptRefs: expected an array")
        for ref_index, ref in enumerate(receipt_refs):
            if not isinstance(ref, str):
                raise ContractError(f"{context}.receiptRefs[{ref_index}]: expected a string")
            normalized_ref = _require_portable_relative_path(
                ref, f"{context}.receiptRefs[{ref_index}]"
            )
            if not normalized_ref.startswith("artifacts/"):
                raise ContractError(
                    f"{context}.receiptRefs[{ref_index}]: expected a file under artifacts/"
                )
            receipt_refs[ref_index] = normalized_ref
            _require_scan_local_file(
                scan_dir, normalized_ref, f"{context}.receiptRefs[{ref_index}]"
            )
    for field in ("explicitExclusions", "deferred"):
        if not isinstance(coverage.get(field, []), list):
            raise ContractError(f"coverage.{field}: expected an array")
    for index, deferred in enumerate(coverage.get("deferred", [])):
        if isinstance(deferred, dict):
            _validate_deferred_paths(deferred, f"coverage.deferred[{index}]")
    _validate_resolved_deferred(coverage)
    _require_safe_json_value(coverage, "coverage.json")


def _require_unique_artifact_path(artifact: Any, context: str, collision_keys: set[str]) -> str:
    if not isinstance(artifact, dict):
        raise ContractError(f"{context}: expected an object")
    value = _require_str(artifact, "path", context)
    path = _require_portable_relative_path(value, f"{context}.path")
    collision_key = path.lower()
    if collision_key in collision_keys:
        raise ContractError(f"{context}.path: duplicate artifact path")
    collision_keys.add(collision_key)
    return path


def _validate_manifest(manifest: dict[str, Any]) -> None:
    if manifest.get("documentType") != "codex-security.scan-manifest":
        raise ContractError("manifest.documentType: expected codex-security.scan-manifest")
    if manifest.get("schemaVersion") != SCHEMA_VERSION:
        raise ContractError(f"manifest.schemaVersion: expected {SCHEMA_VERSION}")
    scan = _require_dict(manifest, "scan", "manifest")
    for key in ("id", "startedAt", "completedAt", "sealedAt"):
        _require_str(scan, key, "manifest.scan")
    if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
        raise ContractError("manifest.scan.status: expected a terminal scan outcome")
    producer = _require_dict(scan, "producer", "manifest.scan")
    _require_str(producer, "name", "manifest.scan.producer")
    _require_str(producer, "version", "manifest.scan.producer")
    _validate_target(_require_dict(scan, "target", "manifest.scan"))
    scope = _require_dict(scan, "scope", "manifest.scan")
    for field in ("includePaths", "excludePaths"):
        values = _require_list(scope, field, "manifest.scan.scope")
        for index, value in enumerate(values):
            if not isinstance(value, str):
                raise ContractError(f"manifest.scan.scope.{field}[{index}]: expected a string")
            _require_safe_relative_path(
                value, f"manifest.scan.scope.{field}[{index}]", allow_dot=True
            )
    _validate_contract_refs(scan)
    artifacts = _require_list(scan, "artifacts", "manifest.scan")
    if not artifacts:
        raise ContractError("manifest.scan.artifacts: expected generated artifact records")
    artifact_paths: set[str] = set()
    artifact_collision_keys: set[str] = set()
    for index, artifact in enumerate(artifacts):
        context = f"manifest.scan.artifacts[{index}]"
        path = _require_unique_artifact_path(artifact, context, artifact_collision_keys)
        artifact_paths.add(path)
        _require_str(artifact, "sha256", context)
        _require_str(artifact, "mediaType", context)
    for required_path in ("findings.json", *(["coverage.json"] if "coverageRef" in scan else [])):
        if required_path not in artifact_paths:
            raise ContractError(
                f"manifest.scan.artifacts: missing required artifact: {required_path}"
            )
    _require_safe_json_value(manifest, "scan-manifest.json")


def _validate_findings(manifest: dict[str, Any], findings: dict[str, Any]) -> None:
    if findings.get("documentType") != "codex-security.findings":
        raise ContractError("findings.documentType: expected codex-security.findings")
    if findings.get("schemaVersion") != SCHEMA_VERSION:
        raise ContractError(f"findings.schemaVersion: expected {SCHEMA_VERSION}")
    scan_id = _require_str(_require_dict(manifest, "scan", "manifest"), "id", "manifest.scan")
    if findings.get("scanId") != scan_id:
        raise ContractError("findings.scanId: must match manifest scan id")
    finding_ids: set[str] = set()
    occurrence_ids: set[str] = set()
    for index, finding in enumerate(_require_list(findings, "findings", "findings")):
        context = f"findings.findings[{index}]"
        if not isinstance(finding, dict):
            raise ContractError(f"{context}: expected an object")
        _validate_finding(finding, context)
        finding_id = str(finding["findingId"])
        occurrence_id = str(finding["occurrenceId"])
        if finding_id in finding_ids or occurrence_id in occurrence_ids:
            raise ContractError(f"{context}: duplicate finding or occurrence id")
        finding_ids.add(finding_id)
        occurrence_ids.add(occurrence_id)
    _require_safe_json_value(findings, "findings.json")


_SCHEMA_TYPES = {
    "array": list,
    "boolean": bool,
    "integer": int,
    "number": (int, float),
    "object": dict,
    "string": str,
}


def _schema_type_matches(value: Any, expected: str) -> bool:
    if expected == "null":
        return value is None
    return isinstance(value, _SCHEMA_TYPES[expected]) and (
        expected not in ("integer", "number") or not isinstance(value, bool)
    )


def _schema_values_equal(left: Any, right: Any) -> bool:
    if (
        isinstance(left, (int, float))
        and not isinstance(left, bool)
        and isinstance(right, (int, float))
        and not isinstance(right, bool)
    ):
        return left == right
    if type(left) is not type(right):
        return False
    if isinstance(left, dict):
        return left.keys() == right.keys() and all(
            _schema_values_equal(left[key], right[key]) for key in left
        )
    if isinstance(left, list):
        return len(left) == len(right) and all(
            _schema_values_equal(left_item, right_item)
            for left_item, right_item in zip(left, right, strict=True)
        )
    return left == right


def _resolve_schema_reference(
    root_schema: dict[str, Any], reference: str, context: str
) -> dict[str, Any]:
    if reference == "#":
        return root_schema
    if not reference.startswith("#/"):
        raise ContractError(f"{context}: unsupported schema reference {reference!r}")
    target: Any = root_schema
    for raw_part in reference[2:].split("/"):
        part = raw_part.replace("~1", "/").replace("~0", "~")
        if not isinstance(target, dict) or part not in target:
            raise ContractError(f"{context}: unresolved schema reference {reference!r}")
        target = target[part]
    if not isinstance(target, dict):
        raise ContractError(f"{context}: schema reference {reference!r} is not an object")
    return target


def _matches_sealed_path_exclusion(value: str, one_of: Any) -> bool:
    # The empty alternative always matches, so a path must not match the second one.
    if not isinstance(one_of, list) or len(one_of) != 2 or one_of[0] != {}:
        return False
    excluded = one_of[1]
    return (
        isinstance(excluded, dict)
        and excluded.keys() == {"$comment", "type", "pattern"}
        and excluded["$comment"] == "invalidSealedDeferredPath"
        and excluded["type"] == "string"
        and isinstance(excluded["pattern"], str)
        and re.search(excluded["pattern"], value) is not None
    )


def _validate_schema_node(
    value: Any,
    schema: dict[str, Any],
    context: str,
    root_schema: dict[str, Any] | None = None,
) -> None:
    root_schema = schema if root_schema is None else root_schema
    alternatives = schema.get("anyOf")
    if isinstance(alternatives, list):
        errors = []
        for alternative in alternatives:
            try:
                _validate_schema_node(value, alternative, context, root_schema)
                break
            except ContractError as exc:
                errors.append(str(exc))
        else:
            raise ContractError(f"{context}: no schema alternative matched: {'; '.join(errors)}")
    reference = schema.get("$ref")
    if reference is not None:
        if not isinstance(reference, str):
            raise ContractError(f"{context}: schema reference must be a string")
        _validate_schema_node(
            value,
            _resolve_schema_reference(root_schema, reference, context),
            context,
            root_schema,
        )
        if len(schema) == 1:
            return
    expected = schema.get("type")
    if isinstance(expected, list):
        if not any(_schema_type_matches(value, item) for item in expected):
            raise ContractError(f"{context}: does not match schema type {expected}")
    elif isinstance(expected, str) and not _schema_type_matches(value, expected):
        raise ContractError(f"{context}: expected schema type {expected}")
    if "const" in schema and not _schema_values_equal(value, schema["const"]):
        raise ContractError(f"{context}: expected {schema['const']!r}")
    if "enum" in schema and not any(
        _schema_values_equal(value, candidate) for candidate in schema["enum"]
    ):
        raise ContractError(f"{context}: unsupported value {value!r}")
    if isinstance(value, str):
        if schema.get("minLength", 0) and len(value) < schema["minLength"]:
            raise ContractError(f"{context}: string is too short")
        if "maxLength" in schema and len(value) > schema["maxLength"]:
            raise ContractError(f"{context}: string is too long")
        if "pattern" in schema and not re.search(schema["pattern"], value):
            raise ContractError(f"{context}: string does not match schema pattern")
        if _matches_sealed_path_exclusion(value, schema.get("oneOf")):
            raise ContractError(f"{context}: string matches excluded schema pattern")
        if schema.get("format") == "date-time":
            _validate_date_time(value, context)
    if isinstance(value, (int, float)) and not isinstance(value, bool):
        if "minimum" in schema and value < schema["minimum"]:
            raise ContractError(f"{context}: value is below schema minimum")
        if "maximum" in schema and value > schema["maximum"]:
            raise ContractError(f"{context}: value is above schema maximum")
    if isinstance(value, list):
        if "minItems" in schema and len(value) < schema["minItems"]:
            raise ContractError(f"{context}: array has too few items")
        if "maxItems" in schema and len(value) > schema["maxItems"]:
            raise ContractError(f"{context}: array has too many items")
        if schema.get("uniqueItems") is True:
            for index, item in enumerate(value):
                if any(_schema_values_equal(item, candidate) for candidate in value[:index]):
                    raise ContractError(f"{context}: array items must be unique")
        contains = schema.get("contains")
        if isinstance(contains, dict):
            matches = 0
            for item in value:
                try:
                    _validate_schema_node(item, contains, context, root_schema)
                except ContractError:
                    pass
                else:
                    matches += 1
            if matches < schema.get("minContains", 1):
                raise ContractError(f"{context}: array contains too few matching items")
            if "maxContains" in schema and matches > schema["maxContains"]:
                raise ContractError(f"{context}: array contains too many matching items")
        item_schema = schema.get("items")
        if isinstance(item_schema, dict):
            for index, item in enumerate(value):
                _validate_schema_node(item, item_schema, f"{context}[{index}]", root_schema)
    if isinstance(value, dict):
        for item_schema in schema.get("allOf", []):
            _validate_schema_node(value, item_schema, context, root_schema)
        condition = schema.get("if")
        if isinstance(condition, dict):
            try:
                _validate_schema_node(value, condition, context, root_schema)
            except ContractError:
                pass
            else:
                then_schema = schema.get("then")
                if isinstance(then_schema, dict):
                    _validate_schema_node(value, then_schema, context, root_schema)
        for key in schema.get("required", []):
            if key not in value:
                raise ContractError(f"{context}.{key}: missing required schema property")
        if "minProperties" in schema and len(value) < schema["minProperties"]:
            raise ContractError(f"{context}: object has too few properties")
        properties = schema.get("properties", {})
        additional_properties = schema.get("additionalProperties", True)
        for key, item in value.items():
            item_schema = properties.get(key)
            if item_schema is False:
                raise ContractError(f"{context}.{key}: unexpected schema property")
            if isinstance(item_schema, dict):
                _validate_schema_node(item, item_schema, f"{context}.{key}", root_schema)
            elif additional_properties is False:
                raise ContractError(f"{context}.{key}: unexpected schema property")
            elif isinstance(additional_properties, dict):
                _validate_schema_node(
                    item,
                    additional_properties,
                    f"{context}.{key}",
                    root_schema,
                )


def validate_against_schema(payload: dict[str, Any], schema_path: Path) -> None:
    schema = _read_json(schema_path)
    _validate_schema_node(payload, schema, schema_path.stem, schema)


def _current_finding_definition(schema_dir: Path, name: str) -> dict[str, Any]:
    draft = _read_json(schema_dir / "tools" / "scan-draft.schema.json")
    common = _read_json(schema_dir / "definitions" / "artifact-common.schema.json")
    documents = {document["$id"]: document for document in (draft, common)}

    def resolve(node: Any) -> Any:
        if isinstance(node, list):
            return [resolve(item) for item in node]
        if not isinstance(node, dict):
            return node
        resolved = {key: resolve(value) for key, value in node.items() if key != "$ref"}
        if "$ref" in node:
            document_id, fragment = node["$ref"].split("#", 1)
            referenced = _resolve_schema_reference(
                documents[document_id], f"#{fragment}", "finding schema"
            )
            resolved = {**resolve(referenced), **resolved}
        return resolved

    return resolve(draft["$defs"][name])


def _validate_current_findings(findings: dict[str, Any], schema_dir: Path) -> None:
    """Use the model's current finding contract for new completed results."""
    finding_schema = _current_finding_definition(schema_dir, "finding")
    for index, finding in enumerate(findings["findings"]):
        # These fields belong to the host, not the authored finding contract.
        authored = {
            key: value
            for key, value in finding.items()
            if key not in {"findingId", "occurrenceId", "fingerprints"}
        }
        _validate_schema_node(authored, finding_schema, f"findings.findings[{index}]")


def _validate_contract_refs(scan: dict[str, Any]) -> None:
    for field, expected in (
        ("coverageRef", "coverage.json"),
        ("findingsRef", "findings.json"),
    ):
        if field == "coverageRef" and field not in scan:
            continue
        actual = _require_str(scan, field, "manifest.scan")
        if actual != expected:
            raise ContractError(f"manifest.scan.{field}: expected {expected!r}")


def _sarif_label(value: str) -> str:
    words = re.sub(r"[-_./]+", " ", value).split()
    acronyms = {"api", "csrf", "html", "http", "id", "rce", "sql", "ssrf", "url", "xml", "xss"}
    label = " ".join(word.upper() if word.lower() in acronyms else word for word in words)
    return label[:1].upper() + label[1:]


def _sarif_rule(rule_id: str, findings: list[dict[str, Any]]) -> dict[str, Any]:
    name = ": ".join(_sarif_label(part) for part in rule_id.split("."))
    categories = sorted({finding["taxonomy"]["category"] for finding in findings})
    cwes = sorted({cwe for finding in findings for cwe in finding["taxonomy"]["cwe"]})
    tags = {"security", *categories}
    for cwe in cwes:
        match = re.fullmatch(r"CWE-([0-9]+)", cwe, re.IGNORECASE)
        if match and (digits := match[1].lstrip("0")):
            tags.add(f"external/cwe/cwe-{digits.zfill(3)}")
    description = f"{name}. Categories: {', '.join(map(_sarif_label, categories))}."
    if cwes:
        description += f" Weaknesses: {', '.join(cwes)}."
    remediation = "\n\n".join(sorted({finding["remediation"] for finding in findings}))
    properties: dict[str, Any] = {"tags": sorted(tags)}
    # GitHub assigns security severity to the shared rule, not each result.
    score = max(
        finding["severity"].get("score", SARIF_SECURITY_SCORES[finding["severity"]["level"]])
        for finding in findings
    )
    if score > 0:
        properties["security-severity"] = str(score)
    return {
        "id": rule_id,
        "name": name,
        "shortDescription": {"text": name},
        "fullDescription": {"text": description},
        "help": {
            "text": f"{description}\n\nRemediation:\n\n{remediation}",
            "markdown": f"{description}\n\n## Remediation\n\n{remediation}",
        },
        "properties": properties,
    }


def _sarif_finding_message(finding: dict[str, Any]) -> str:
    taxonomy = finding["taxonomy"]
    details = [
        finding["title"],
        finding["summary"],
        f"Severity: {finding['severity']['level']}",
        f"Category: {_sarif_label(taxonomy['category'])}",
    ]
    if taxonomy["cwe"]:
        details.append(f"Weaknesses: {', '.join(taxonomy['cwe'])}")
    details.append(f"Remediation:\n{finding['remediation']}")
    for key, label in (
        ("remediationTests", "Remediation tests"),
        ("preventiveControls", "Preventive controls"),
    ):
        if finding.get(key):
            details.append(f"{label}:\n" + "\n".join(f"- {item}" for item in finding[key]))
    return "\n\n".join(details)


def _github_line_hashes(
    handle: TextIO,
    requested_lines: set[int] | None = None,
) -> dict[int, str]:
    window = [0] * GITHUB_HASH_BLOCK_SIZE
    line_numbers = [-1] * GITHUB_HASH_BLOCK_SIZE
    hash_counts: dict[str, int] = {}
    hashes: dict[int, str] = {}
    first_mod = pow(GITHUB_HASH_MOD, GITHUB_HASH_BLOCK_SIZE, 1 << 64)
    hash_raw = 0
    index = 0
    line_number = 0
    line_start = True
    previous_was_cr = False

    def output_hash() -> None:
        nonlocal index
        hash_value = format(hash_raw & GITHUB_HASH_MASK, "x")
        hash_counts[hash_value] = hash_counts.get(hash_value, 0) + 1
        line_number = line_numbers[index]
        if requested_lines is None or line_number in requested_lines:
            hashes[line_number] = f"{hash_value}:{hash_counts[hash_value]}"
        line_numbers[index] = -1

    def update_hash(current: int) -> None:
        nonlocal hash_raw, index
        beginning = window[index]
        window[index] = current
        hash_raw = (GITHUB_HASH_MOD * hash_raw + current - first_mod * beginning) & GITHUB_HASH_MASK
        index = (index + 1) % GITHUB_HASH_BLOCK_SIZE

    def process_character(current: int) -> None:
        nonlocal line_number, line_start, previous_was_cr
        if current in {ord(" "), ord("\t")} or (previous_was_cr and current == ord("\n")):
            previous_was_cr = False
            return
        if current == ord("\r"):
            current = ord("\n")
            previous_was_cr = True
        else:
            previous_was_cr = False
        if line_numbers[index] != -1:
            output_hash()
        if line_start:
            line_start = False
            line_number += 1
            line_numbers[index] = line_number
        if current == ord("\n"):
            line_start = True
        update_hash(current)

    while chunk := handle.read(SOURCE_READ_CHUNK_SIZE):
        for (code_unit,) in struct.iter_unpack("<H", chunk.encode("utf-16-le")):
            process_character(code_unit)
    process_character(GITHUB_HASH_EOF)
    for _ in range(GITHUB_HASH_BLOCK_SIZE):
        if line_numbers[index] != -1:
            output_hash()
        update_hash(0)
    return hashes


def _open_source_file(source_root: Path, relative_path: str) -> TextIO | None:
    file_fd: int | None = None
    try:
        file_fd = open_scan_local_file_descriptor(
            source_root, relative_path, f"source file {relative_path}", portable=False
        )
        handle = os.fdopen(file_fd, "r", encoding="utf-8", errors="replace")
        file_fd = None
        return handle
    except (ContractError, OSError, ValueError):
        return None
    finally:
        if file_fd is not None:
            os.close(file_fd)


def _github_line_hashes_for_source(
    source_root: Path,
    relative_path: str,
    requested_lines: set[int] | None = None,
) -> dict[int, str] | None:
    handle = _open_source_file(source_root, relative_path)
    if handle is None:
        return None
    try:
        with handle:
            return _github_line_hashes(handle, requested_lines)
    except OSError:
        return None


def _sarif_primary_location(finding: dict[str, Any]) -> dict[str, Any]:
    return next(
        (location for location in finding["locations"] if location.get("role") == "root_control"),
        finding["locations"][0],
    )


def _merged_code_evidence(finding: dict[str, Any]) -> list[dict[str, Any]]:
    catalog: dict[str, dict[str, Any]] = {}
    for evidence_key in ("codeEvidence", "code_evidence"):
        code_evidence = finding.get(evidence_key)
        if not isinstance(code_evidence, list):
            continue
        for evidence in code_evidence:
            if not isinstance(evidence, dict):
                continue
            evidence_id = evidence.get("id")
            if isinstance(evidence_id, str) and evidence_id:
                catalog.setdefault(evidence_id, evidence)
    return list(catalog.values())


def _finding_evidence_strength(finding: dict[str, Any]) -> int:
    evidence = _merged_code_evidence(finding)
    seen_ids = {
        item["id"] for item in evidence if isinstance(item.get("id"), str) and item["id"].strip()
    }
    seen_codes = {
        item["code"]
        for item in evidence
        if isinstance(item.get("code"), str) and item["code"].strip()
    }
    strength = len(evidence)
    for section_name in ("rootCause", "root_cause"):
        section = finding.get(section_name)
        if not isinstance(section, dict):
            continue
        for item in report_projection.embedded_code_evidence(section):
            code = item["code"]
            if code in seen_codes:
                continue
            evidence_id = item.get("id")
            if isinstance(evidence_id, str) and evidence_id.strip():
                if evidence_id in seen_ids:
                    continue
                seen_ids.add(evidence_id)
            seen_codes.add(code)
            strength += 1
        code = section.get("code")
        if isinstance(code, str) and code.strip() and code not in seen_codes:
            seen_codes.add(code)
            strength += 1
    return strength


def _sarif_locations(finding: dict[str, Any]) -> list[dict[str, Any]]:
    primary = _sarif_primary_location(finding)
    locations = [
        primary,
        *(location for location in finding["locations"] if location is not primary),
    ]
    for evidence in _merged_code_evidence(finding):
        path = evidence.get("path")
        start_line = evidence.get("startLine")
        if (
            not isinstance(path, str)
            or not isinstance(start_line, int)
            or isinstance(start_line, bool)
            or start_line < 1
        ):
            continue
        try:
            path = _require_safe_relative_path(path, "SARIF evidence location")
        except ContractError:
            continue
        locations.append(
            {
                "path": path,
                "startLine": start_line,
                "endLine": (
                    evidence["endLine"]
                    if isinstance(evidence.get("endLine"), int)
                    and not isinstance(evidence["endLine"], bool)
                    and evidence["endLine"] >= start_line
                    else start_line
                ),
                "role": f"evidence:{evidence['id']}",
            }
        )
    unique: dict[tuple[str, int, int], dict[str, Any]] = {}
    for location in locations:
        key = (
            PurePosixPath(location["path"]).as_posix(),
            location["startLine"],
            location.get("endLine", location["startLine"]),
        )
        unique.setdefault(key, location)
    return list(unique.values())


def _github_line_hash_cache(
    findings: list[dict[str, Any]], source_root: Path | None
) -> dict[tuple[Path, int], str | None]:
    if source_root is None:
        return {}
    try:
        source_root = source_root.resolve(strict=True)
    except (OSError, RuntimeError):
        return {}
    requested_lines_by_path: dict[str, set[int]] = {}
    for finding in findings:
        primary_location = _sarif_primary_location(finding)
        relative_path = _require_safe_relative_path(
            primary_location["path"], "SARIF source location"
        )
        requested_lines_by_path.setdefault(relative_path, set()).add(primary_location["startLine"])
    line_hash_cache: dict[tuple[Path, int], str | None] = {}
    for relative_path, requested_lines in requested_lines_by_path.items():
        line_hashes = _github_line_hashes_for_source(source_root, relative_path, requested_lines)
        source_path = Path(relative_path)
        for line_number in requested_lines:
            line_hash_cache[(source_path, line_number)] = (
                None if line_hashes is None else line_hashes.get(line_number)
            )
    return line_hash_cache


def _sarif_location(location: dict[str, Any]) -> dict[str, Any]:
    sarif_location: dict[str, Any] = {
        "physicalLocation": {
            "artifactLocation": {
                "uri": quote(location["path"], safe="/"),
            },
            "region": {
                "startLine": location["startLine"],
                "endLine": location.get("endLine", location["startLine"]),
            },
        }
    }
    if location.get("role"):
        sarif_location["message"] = {"text": location["role"]}
    return sarif_location


def _sarif_result(
    finding: dict[str, Any],
    rule_index: int,
    line_hash_cache: dict[tuple[Path, int], str | None] | None = None,
) -> dict[str, Any]:
    properties = {
        "category": finding["taxonomy"]["category"],
        "confidence": finding["confidence"]["level"],
        "findingId": finding["findingId"],
        "occurrenceId": finding["occurrenceId"],
        "severity": finding["severity"]["level"],
    }
    extensions = finding.get("extensions")
    candidate_id = extensions.get("candidateId") if isinstance(extensions, dict) else None
    if isinstance(candidate_id, str) and candidate_id:
        properties["candidateId"] = candidate_id
    partial_fingerprints = {
        "codexSecurity/v1": finding["fingerprints"]["primary"],
    }
    primary = _sarif_primary_location(finding)
    line_hash = (line_hash_cache or {}).get((Path(primary["path"]), primary["startLine"]))
    if line_hash is not None:
        partial_fingerprints["primaryLocationLineHash"] = line_hash
    return {
        "ruleId": finding["ruleId"],
        "ruleIndex": rule_index,
        "level": SARIF_LEVELS[finding["severity"]["level"]],
        "message": {"text": _sarif_finding_message(finding)},
        "locations": [_sarif_location(location) for location in _sarif_locations(finding)],
        "partialFingerprints": partial_fingerprints,
        "properties": properties,
    }


def build_sarif(
    manifest: dict[str, Any], findings: dict[str, Any], source_root: Path | None = None
) -> dict[str, Any]:
    scan = manifest["scan"]
    target = scan["target"]
    ordered_findings = sorted(findings["findings"], key=lambda finding: finding["occurrenceId"])
    findings_by_rule: dict[str, list[dict[str, Any]]] = {}
    for finding in ordered_findings:
        findings_by_rule.setdefault(finding["ruleId"], []).append(finding)
    ordered_rule_ids = sorted(findings_by_rule)
    rule_index = {rule_id: index for index, rule_id in enumerate(ordered_rule_ids)}
    line_hash_cache = _github_line_hash_cache(ordered_findings, source_root)
    run: dict[str, Any] = {
        "tool": {
            "driver": {
                "name": "Codex Security",
                "version": scan["producer"]["version"],
                "rules": [
                    _sarif_rule(rule_id, findings_by_rule[rule_id]) for rule_id in ordered_rule_ids
                ],
            }
        },
        "automationDetails": {"id": scan["id"]},
        "results": [
            _sarif_result(finding, rule_index[finding["ruleId"]], line_hash_cache)
            for finding in ordered_findings
        ],
        "properties": {
            "codexSecuritySchemaVersion": manifest["schemaVersion"],
            "codexSecurityTargetKind": target["kind"],
        },
    }
    if target["kind"] == "git_revision" and target.get("remote") and target.get("revision"):
        run["versionControlProvenance"] = [
            {
                "repositoryUri": target["remote"],
                "revisionId": target["revision"],
            }
        ]
    return {
        "$schema": SARIF_SCHEMA,
        "version": "2.1.0",
        "runs": [run],
    }


def _artifact_record(
    scan_dir: Path, relative_path: str, media_type: str, contents: bytes | None = None
) -> dict[str, str]:
    relative_path = _require_portable_relative_path(relative_path, "artifact path")
    if contents is not None:
        _validate_scan_local_output_path(scan_dir, scan_dir / relative_path, relative_path)
    return {
        "mediaType": media_type,
        "path": relative_path,
        "sha256": (
            hashlib.sha256(contents).hexdigest()
            if contents is not None
            else _sha256_scan_local_file(scan_dir, relative_path, relative_path)
        ),
    }


def _supplementary_artifact_refs(scan: dict[str, Any], coverage: dict[str, Any]) -> dict[str, str]:
    refs = {
        ref: "coverage receipt"
        for surface in coverage["surfaces"]
        for ref in surface.get("receiptRefs", [])
    }
    extensions = scan.get("extensions")
    imported = extensions.get("import") if isinstance(extensions, dict) else None
    if isinstance(imported, dict) and "sourceRef" in imported:
        context = "manifest.scan.extensions.import"
        ref = _require_portable_relative_path(
            _require_str(imported, "sourceRef", context), f"{context}.sourceRef"
        )
        if not ref.startswith("artifacts/"):
            raise ContractError(f"{context}.sourceRef: expected a file under artifacts/")
        refs.setdefault(ref, "import source")
    return {ref: refs[ref] for ref in sorted(refs)}


def _validate_sealed_coverage_receipts(scan: dict[str, Any], coverage: dict[str, Any]) -> None:
    artifact_paths = {
        _require_portable_relative_path(artifact["path"], "sealed artifact path")
        for artifact in scan["artifacts"]
    }
    for ref, context in _supplementary_artifact_refs(scan, coverage).items():
        if ref not in artifact_paths:
            raise ContractError(f"{context} is missing from sealed artifacts: {ref}")


def _validate_existing_seal(
    scan_dir: Path,
    scan: dict[str, Any],
    *,
    artifact_contents: dict[str, bytes] | None = None,
) -> None:
    sealed_at = scan.get("sealedAt")
    artifacts = scan.get("artifacts")
    if sealed_at is None and artifacts is None:
        return
    if sealed_at != scan.get("completedAt"):
        raise ContractError("manifest.scan.sealedAt: must match completedAt")
    if not isinstance(artifacts, list) or not artifacts:
        raise ContractError("manifest.scan.artifacts: sealed manifest requires artifact records")
    artifact_collision_keys: set[str] = set()
    for index, artifact in enumerate(artifacts):
        context = f"manifest.scan.artifacts[{index}]"
        path = _require_unique_artifact_path(artifact, context, artifact_collision_keys)
        expected_sha256 = _require_str(artifact, "sha256", context)
        contents = (artifact_contents or {}).get(path)
        actual_sha256 = (
            hashlib.sha256(contents).hexdigest()
            if contents is not None
            else _sha256_scan_local_file(scan_dir, path, context)
        )
        if actual_sha256 != expected_sha256:
            raise ContractError(f"{context}: sealed artifact changed or is missing")


def _read_scan_artifacts(
    scan_dir: Path, scan: dict[str, Any]
) -> tuple[dict[str, Any], dict[str, Any], dict[str, bytes]]:
    findings, findings_bytes = _read_scan_local_json_bytes(
        scan_dir, scan["findingsRef"], scan["findingsRef"]
    )
    contents = {scan["findingsRef"]: findings_bytes}
    if "coverageRef" in scan:
        coverage, coverage_bytes = _read_scan_local_json_bytes(
            scan_dir, scan["coverageRef"], scan["coverageRef"]
        )
        contents[scan["coverageRef"]] = coverage_bytes
    else:
        coverage = review_state(scan)
    return findings, coverage, contents


def _read_sealed_artifacts(
    scan_dir: Path, scan: dict[str, Any]
) -> tuple[dict[str, Any], dict[str, Any], bytes]:
    findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
    _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
    return findings, coverage, contents[scan["findingsRef"]]


def _read_sealed_scan(
    scan_dir: Path, schema_dir: Path | None, required_for: str
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], bytes]:
    scan_dir = _require_scan_directory(scan_dir)
    schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
    manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
    scan = _require_dict(manifest, "scan", "manifest")
    _validate_contract_refs(scan)
    if scan.get("sealedAt") is None or scan.get("artifacts") is None:
        raise ContractError(f"manifest.scan: {required_for} requires a sealed scan")
    findings, coverage, findings_bytes = _read_sealed_artifacts(scan_dir, scan)
    _validate_manifest(manifest)
    findings_for_validation = _legacy_sealed_findings_for_validation(findings)
    _validate_findings(manifest, findings_for_validation)
    _validate_coverage(manifest, coverage, scan_dir)
    _validate_sealed_coverage_receipts(scan, coverage)
    validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
    validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
    validate_against_schema(coverage, schema_dir / "coverage.schema.json")
    _validate_derived_finding_identities(manifest, findings)
    return manifest, findings, coverage, findings_bytes


def build_sarif_projection(
    scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
) -> dict[str, Any]:
    """Build SARIF for a sealed scan, using the optional source directory to resolve locations."""
    if source_root is not None:
        try:
            source_root = source_root.resolve(strict=True)
            source_root_is_directory = source_root.is_dir()
        except (OSError, RuntimeError):
            source_root_is_directory = False
        if not source_root_is_directory:
            raise ContractError("source root: expected an existing directory")
    manifest, findings, coverage, _ = _read_sealed_scan(scan_dir, schema_dir, "SARIF projection")
    sarif = build_sarif(manifest, findings, source_root)
    execution_successful = manifest["scan"]["status"] == "completed"
    messages = [item["reason"] for item in coverage["deferred"]]
    for warning in manifest["scan"].get("warnings", []):
        if warning not in messages:
            messages.append(warning)
    if not execution_successful or messages:
        run = sarif["runs"][0]
        run["invocations"] = [
            {
                "executionSuccessful": execution_successful,
                "toolExecutionNotifications": [
                    {"level": "warning", "message": {"text": message}} for message in messages
                ],
            }
        ]
    return sarif


def write_sarif_projection(
    scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
) -> None:
    sarif = build_sarif_projection(scan_dir, source_root, schema_dir)
    relative_path = EXPORT_PATHS["sarif"]
    write_export_output(
        scan_dir, scan_dir / relative_path, "sarif", _contract_json_bytes(relative_path, sarif)
    )


def csv_cell(value: Any) -> Any:
    if isinstance(value, str) and (
        value.startswith(("'", "\t", "\r", "\n"))
        or value.lstrip().startswith(("=", "+", "-", "@", "=", "+", "-", "@"))
    ):
        return f"'{value}"
    return value


def _has_identity_text(value: Any) -> bool:
    # Match JavaScript String.trim when selecting optional identity metadata.
    return isinstance(value, str) and bool(
        value.strip(
            "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680"
            "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a"
            "\u2028\u2029\u202f\u205f\u3000\ufeff"
        )
    )


def _candidate_id_values(finding: dict[str, Any]) -> Iterator[Any]:
    if isinstance(provenance := finding.get("provenance"), dict):
        yield provenance.get("candidateId")
    if isinstance(extensions := finding.get("extensions"), dict):
        for key in ("candidateId", "reportId", "ledgerRowId"):
            yield extensions.get(key)


def finding_candidate_id(finding: dict[str, Any]) -> str | None:
    return next(
        (value for value in _candidate_id_values(finding) if _has_identity_text(value)), None
    )


def _csv_candidate_id(finding: dict[str, Any]) -> str | None:
    # Preserve literal CSV metadata, such as FEFF, that is not a canonical identity.
    return finding_candidate_id(finding) or next(
        (
            value
            for value in _candidate_id_values(finding)
            if isinstance(value, str) and value.strip()
        ),
        None,
    )


def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
    return (
        "occurrence_id",
        "finding_id",
        *(("candidate_id",) if deep_scan else ()),
        "title",
        "summary",
        "severity",
        "confidence",
        "status",
        "close_reason",
        "note",
        "remediation",
        "path",
        "start_line",
        "end_line",
    )


def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
    """Encode findings in input order as UTF-8 CSV using the columns selected by coverage and findings."""
    output = io.StringIO(newline="")
    writer = csv.writer(output)
    deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
    writer.writerow(finding_csv_columns(deep_scan))
    for finding in findings["findings"]:
        location = _sarif_primary_location(finding)
        writer.writerow(
            (
                csv_cell(finding["occurrenceId"]),
                csv_cell(finding["findingId"]),
                *((csv_cell(_csv_candidate_id(finding)),) if deep_scan else ()),
                csv_cell(finding["title"]),
                csv_cell(finding["summary"]),
                csv_cell(finding["severity"]["level"]),
                csv_cell(finding["confidence"]["level"]),
                "open",
                "",
                "",
                csv_cell(finding["remediation"]),
                csv_cell(location["path"]),
                location["startLine"],
                location.get("endLine", location["startLine"]),
            )
        )
    return output.getvalue().encode("utf-8")


def _avit_fields(finding: dict[str, Any]) -> dict[str, str]:
    attack_path = dict(finding.get("attackPath") or {})
    _normalize_legacy_string_list_fields(attack_path, ("steps",))
    steps = "\n".join(attack_path.get("steps", []))
    return servicenow_avit.finding_fields(
        finding, _sarif_primary_location(finding), csv_cell(steps)
    )


def build_findings_export(
    scan_dir: Path,
    export_format: str,
    source_root: Path | None = None,
    schema_dir: Path | None = None,
    avit_template: Path | None = None,
) -> bytes:
    """Return bytes for the requested export of a sealed scan.

    JSON preserves the sealed findings bytes. SARIF can use source_root to resolve
    locations. ServiceNow AVIT requires an application template.
    """
    if export_format not in EXPORT_PATHS:
        raise ContractError(f"unsupported export format: {export_format}")
    if export_format == "sarif":
        return _json_bytes(build_sarif_projection(scan_dir, source_root, schema_dir))
    if source_root is not None:
        raise ContractError("source-root is only supported for SARIF exports")
    _, findings, coverage, findings_bytes = _read_sealed_scan(
        scan_dir, schema_dir, f"{export_format.upper()} export"
    )
    if export_format == "json":
        return findings_bytes
    if export_format == "servicenow-avit":
        if avit_template is None:
            raise ContractError("--export-format servicenow-avit requires --avit-template")
        try:
            return servicenow_avit.render(avit_template, map(_avit_fields, findings["findings"]))
        except ValueError as exc:
            raise ContractError(str(exc)) from exc
    return build_csv_projection(findings, coverage)


def _is_sealed_artifact(scan_dir: Path, relative_output: str, artifact_paths: list[str]) -> bool:
    try:
        output_metadata = (scan_dir / relative_output).stat(follow_symlinks=False)
    except FileNotFoundError:
        output_metadata = None
    except OSError as exc:
        raise ContractError(f"{relative_output}: unable to inspect export output") from exc
    for artifact_path in artifact_paths:
        if artifact_path == relative_output:
            return True
        if output_metadata is None:
            continue
        descriptor = open_scan_local_file_descriptor(
            scan_dir, artifact_path, f"sealed artifact {artifact_path}"
        )
        try:
            artifact_metadata = os.fstat(descriptor)
        finally:
            os.close(descriptor)
        if os.path.samestat(output_metadata, artifact_metadata):
            return True
    return False


def write_export_output(
    scan_dir: Path,
    output: Path,
    export_format: str,
    contents: bytes,
    *,
    replace_existing: bool = True,
) -> None:
    output_paths = {**EXPORT_PATHS, "md": THREAT_MODEL_EXPORT_PATH}
    if export_format not in output_paths:
        raise ContractError(f"unsupported export format: {export_format}")
    scan_dir = _require_scan_directory(scan_dir)
    output = Path(os.path.abspath(output))
    try:
        relative_output = output.relative_to(scan_dir).as_posix()
    except ValueError:
        for ancestor in output.parents:
            try:
                inside_scan = ancestor.samefile(scan_dir)
            except FileNotFoundError:
                continue
            except OSError as exc:
                raise ContractError(
                    "export output path: unable to inspect output directory"
                ) from exc
            if inside_scan:
                if any(parent.is_symlink() for parent in (ancestor, *ancestor.parents)):
                    raise ContractError(
                        "export output path: symbolic links cannot alias the scan directory"
                    ) from None
                relative_output = output.relative_to(ancestor).as_posix()
                break
        else:
            write_scan_local_bytes(
                output.parent,
                output.name,
                contents,
                external_name=True,
                replace_existing=replace_existing,
                owner_read_write=export_format == "md",
            )
            return
    if relative_output != output_paths[export_format]:
        raise ContractError(f"{export_format.upper()} output path cannot overwrite a scan artifact")
    if (scan_dir / "scan-manifest.json").exists():
        manifest = _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
        scan = _require_dict(manifest, "scan", "manifest")
        artifacts = scan.get("artifacts", [])
    else:
        artifacts = []
    artifact_paths = [
        _require_portable_relative_path(
            _require_str(artifact, "path", f"manifest.scan.artifacts[{index}]"),
            f"manifest.scan.artifacts[{index}].path",
        )
        for index, artifact in enumerate(artifacts)
        if isinstance(artifact, dict)
    ]
    if _is_sealed_artifact(scan_dir, relative_output, artifact_paths):
        raise SealedArtifactError(
            f"{export_format.upper()} output path cannot overwrite a sealed scan artifact"
        )
    write_scan_local_bytes(
        scan_dir,
        relative_output,
        contents,
        owner_read_write=export_format == "md",
        replace_existing=replace_existing,
    )


def _write_sarif_projection_if_possible(
    scan_dir: Path,
    source_root: Path | None = None,
    schema_dir: Path | None = None,
    *,
    sealed_paths: list[str],
) -> None:
    try:
        if not _is_sealed_artifact(scan_dir, "exports/results.sarif", sealed_paths):
            write_sarif_projection(scan_dir, source_root, schema_dir)
    except (ContractError, OSError) as error:
        print(
            f"codex-security: warning: automatic SARIF export failed: {error}. "
            "Run `codex-security export <scan-dir> --export-format sarif` to retry.",
            file=sys.stderr,
        )


class PreparedScanFinalization(NamedTuple):
    """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""

    scan_dir: Path
    schema_dir: Path
    manifest: dict[str, Any]
    findings: dict[str, Any]
    coverage: dict[str, Any]
    was_sealed: bool
    report_markdown_bytes: bytes
    warnings: list[str]


def manifest_is_sealed(scan: dict[str, Any]) -> bool:
    """Return whether the manifest records a seal time or sealed artifacts."""
    return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])


def _prepare_scan_finalization(
    scan_dir: Path,
    schema_dir: Path | None = None,
    *,
    expected_coverage_mode: str | None = None,
    completion_binding: dict[str, Any] | None = None,
    recover_unsealed: bool = False,
    allow_missing_writeups: bool = False,
    draft_documents: tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None = None,
    finding_scope: list[tuple[str, bool]] | None = None,
) -> PreparedScanFinalization:
    """Prepare validated documents and warnings without writing any output files."""

    warnings: list[str] = []
    scan_dir = _require_scan_directory(scan_dir)
    schema_dir = schema_dir or Path(__file__).resolve().parent.parent / "schemas"
    manifest = (
        copy.deepcopy(draft_documents[0])
        if draft_documents is not None
        else _read_scan_local_json(scan_dir, "scan-manifest.json", "scan-manifest.json")
    )
    scan = _require_dict(manifest, "scan", "manifest")
    if scan.get("sealedAt") is None and scan.get("artifacts") == []:
        del scan["artifacts"]
    was_sealed = manifest_is_sealed(scan)
    if (
        not was_sealed
        and "review" not in scan
        and "reviewState" not in scan
        and draft_documents is None
        and (scan_dir / "coverage.json").exists()
    ):
        scan["coverageRef"] = "coverage.json"
    if not was_sealed:
        _populate_unsealed_manifest_envelope(manifest, scan, completion_binding)
    _validate_contract_refs(scan)
    if draft_documents is None:
        findings, coverage, contents = _read_scan_artifacts(scan_dir, scan)
    else:
        findings, coverage = copy.deepcopy(draft_documents[1:])
        contents = {scan["findingsRef"]: _json_bytes(findings)}
        if "coverageRef" in scan:
            contents[scan["coverageRef"]] = _json_bytes(coverage)
    if "coverageRef" not in scan:
        _json_bytes(coverage)
    if not was_sealed:
        # Preserve legacy sealed bundles, but do not publish a completeness claim.
        coverage.pop("completeness", None)
        _populate_unsealed_artifact_envelope(manifest, findings, coverage, completion_binding)
        # Label whole-repository Deep scans as using the repository inventory.
        if expected_coverage_mode == "deep_repository":
            coverage["inventoryStrategy"] = "repository"
        _normalize_unsealed_open_questions(coverage)

    if manifest.get("schemaVersion") != SCHEMA_VERSION:
        raise ContractError(f"manifest.schemaVersion: expected {SCHEMA_VERSION}")
    if scan.get("status") not in {"completed", "failed", "canceled", "interrupted"}:
        raise ContractError("manifest.scan.status: expected a terminal scan outcome before sealing")
    if (
        expected_coverage_mode is not None
        and completion_binding is not None
        and completion_binding["coverageMode"] != expected_coverage_mode
    ):
        raise ContractError("completion binding coverage mode does not match expected mode")
    if expected_coverage_mode is not None and coverage.get("mode") != expected_coverage_mode:
        raise ContractError(
            f"coverage.mode: must match selected scan mode {expected_coverage_mode}"
        )
    _validate_existing_seal(scan_dir, scan, artifact_contents=contents)
    scan["sealedAt"] = _require_str(scan, "completedAt", "manifest.scan")
    _validate_target(_require_dict(scan, "target", "manifest.scan"))
    _validate_completion_binding(manifest, findings, coverage, completion_binding)
    findings_for_validation = (
        _legacy_sealed_findings_for_validation(findings) if was_sealed else findings
    )
    discarded_findings: list[str] = []
    if not was_sealed and scan["status"] == "completed":
        try:
            _populate_unsealed_finding_identities(manifest, findings)
            _validate_findings(manifest, findings)
            _validate_current_findings(findings, schema_dir)
        except ContractError as exc:
            raise RecoverableContractError(
                "Scan result contains invalid findings; repair the finding records "
                f"before completion. {exc}"
            ) from exc
    elif not was_sealed and recover_unsealed:
        discarded_findings = _recover_unsealed_findings(
            manifest, findings, schema_dir, scan_dir, warnings
        )
    elif not was_sealed:
        _populate_unsealed_finding_identities(manifest, findings)
    if not was_sealed and recover_unsealed:
        _recover_unsealed_coverage(coverage, schema_dir, scan_dir, warnings, discarded_findings)
        _recover_unsealed_hardening(manifest, scan_dir, warnings)
    if was_sealed or scan["status"] != "completed":
        _validate_findings(manifest, findings_for_validation)
    if was_sealed:
        _validate_derived_finding_identities(manifest, findings)
    _validate_coverage(manifest, coverage, scan_dir)
    provisional_manifest = copy.deepcopy(manifest)
    provisional_manifest["scan"]["artifacts"] = [
        {"path": "findings.json", "sha256": "0" * 64, "mediaType": "application/json"},
        {"path": "coverage.json", "sha256": "0" * 64, "mediaType": "application/json"},
    ]
    inline_review = {}
    if "coverageRef" not in scan:
        inline_review = {"mode": coverage["mode"], "review": review_summary(coverage)}
        provisional_manifest["scan"].update(inline_review)
    validate_against_schema(provisional_manifest, schema_dir / "scan-manifest.schema.json")
    del provisional_manifest
    validate_against_schema(findings_for_validation, schema_dir / "findings.schema.json")
    validate_against_schema(coverage, schema_dir / "coverage.schema.json")
    _require_hardening_portfolio_file(scan_dir, scan)
    if finding_scope is not None:
        # Accepted worker/reducer files remain immutable; only the new parent
        # projection is scoped, after the existing validation of every finding.
        scoped_findings = []
        excluded_findings = []
        for finding in findings["findings"]:
            in_scope = any(
                PurePosixPath(location["path"]) == PurePosixPath(path)
                if is_file
                else path_within_scope(location["path"], path)
                for location in finding["locations"]
                for path, is_file in finding_scope
            )
            (scoped_findings if in_scope else excluded_findings).append(finding)
        if was_sealed and len(scoped_findings) != len(findings["findings"]):
            raise ContractError(
                "The sealed Deep scan contains findings outside its requested paths; "
                "start a new scan to produce scoped results."
            )
        if not was_sealed:
            # Excluded findings still require safe writeups, but missing optional
            # links should only produce warnings for findings in the final report.
            _prepare_derived_writeups(
                scan_dir,
                {"findings": excluded_findings},
                allow_missing=allow_missing_writeups,
            )
            findings["findings"] = scoped_findings
    warnings.extend(
        _prepare_derived_writeups(
            scan_dir,
            findings,
            allow_missing=allow_missing_writeups and not was_sealed,
        )
    )
    if was_sealed:
        _validate_sealed_coverage_receipts(scan, coverage)
        _validate_manifest(manifest)
        validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
        report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
        _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
    else:
        findings_bytes = _contract_json_bytes("findings.json", findings)
        coverage_bytes = _contract_json_bytes("coverage.json", coverage)
        if inline_review:
            scan.update(inline_review)
            scan.pop("reviewState", None)
        report_markdown_bytes = _generate_report_projection(manifest, findings, coverage)
        _validate_scan_local_output_path(scan_dir, scan_dir / "report.md", "report.md")
        scan["artifacts"] = [
            _artifact_record(scan_dir, "findings.json", "application/json", findings_bytes),
            *(
                [_artifact_record(scan_dir, "coverage.json", "application/json", coverage_bytes)]
                if "coverageRef" in scan
                else []
            ),
            *[
                _artifact_record(scan_dir, ref, "application/octet-stream")
                for ref in _supplementary_artifact_refs(scan, coverage)
            ],
        ]
        _validate_manifest(manifest)
        validate_against_schema(manifest, schema_dir / "scan-manifest.schema.json")
        _contract_json_bytes("scan-manifest.json", manifest)
    return PreparedScanFinalization(
        scan_dir=scan_dir,
        schema_dir=schema_dir,
        manifest=manifest,
        findings=findings,
        coverage=coverage,
        was_sealed=was_sealed,
        report_markdown_bytes=report_markdown_bytes,
        warnings=warnings,
    )


def _write_prepared_scan_finalization(
    prepared: PreparedScanFinalization,
    source_root: Path | None = None,
    *,
    projection_warnings: list[str] | None = None,
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    """Write a previously validated scan finalization result."""

    scan_dir = prepared.scan_dir
    scan = _require_dict(prepared.manifest, "scan", "manifest")
    if not prepared.was_sealed:
        # Capture warnings before the first seal; later operation diagnostics must
        # not change an existing scan's portable results.
        # Escape surrogate-escaped filesystem bytes for the Unicode JSON contract.
        warnings = list(
            dict.fromkeys(
                warning.encode("utf-8", errors="backslashreplace").decode("utf-8")
                for warning in [
                    *scan.get("warnings", []),
                    *(projection_warnings or []),
                    *prepared.warnings,
                ]
            )
        )
        if warnings:
            scan["warnings"] = warnings
            validate_against_schema(
                prepared.manifest, prepared.schema_dir / "scan-manifest.schema.json"
            )
        _write_scan_local_json(scan_dir, "findings.json", prepared.findings)
        if "coverageRef" in scan:
            _write_scan_local_json(scan_dir, "coverage.json", prepared.coverage)
        elif "preservedSources" not in scan and not (scan_dir / "checkpoint-head.json").exists():
            checkpoint = {
                "scanId": scan["id"],
                "complete": scan["status"] == "completed",
                "scope": scan["scope"],
                "findings": prepared.findings["findings"],
                "reviewState": checkpoint_review_state(prepared.coverage),
                **({"threatModel": scan["threatModel"]} if "threatModel" in scan else {}),
            }
            contents = _json_bytes(checkpoint)
            name = hashlib.sha256(contents).hexdigest() + ".json"
            write_scan_local_bytes(scan_dir, "checkpoints/" + name, contents)
            _write_scan_local_json(scan_dir, "checkpoint-head.json", {"checkpoint": name})
    if not prepared.was_sealed and "coverageRef" not in scan:
        _remove_scan_local_file_if_exists(scan_dir, "coverage.json")
    sealed_paths = (
        [artifact["path"] for artifact in scan["artifacts"]] if prepared.was_sealed else []
    )
    if not _is_sealed_artifact(scan_dir, "report.md", sealed_paths):
        write_scan_local_bytes(scan_dir, "report.md", prepared.report_markdown_bytes)
    if not _is_sealed_artifact(scan_dir, "report.html", sealed_paths):
        _remove_scan_local_file_if_exists(scan_dir, "report.html")
    if not prepared.was_sealed:
        _write_scan_local_json(scan_dir, "scan-manifest.json", prepared.manifest)
        _validate_existing_seal(scan_dir, scan)
    _write_sarif_projection_if_possible(
        scan_dir, source_root, prepared.schema_dir, sealed_paths=sealed_paths
    )
    warning = write_threat_model_projection_if_possible(scan_dir, prepared.manifest)
    if (
        warning is not None
        and projection_warnings is not None
        and warning not in projection_warnings
    ):
        projection_warnings.append(warning)
    return prepared.manifest, prepared.findings, prepared.coverage


def finalize_scan(
    scan_dir: Path,
    schema_dir: Path | None = None,
    source_root: Path | None = None,
    *,
    expected_coverage_mode: str | None = None,
    completion_binding: dict[str, Any] | None = None,
    projection_warnings: list[str] | None = None,
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    prepared = _prepare_scan_finalization(
        scan_dir,
        schema_dir,
        expected_coverage_mode=expected_coverage_mode,
        completion_binding=completion_binding,
    )
    return _write_prepared_scan_finalization(
        prepared, source_root, projection_warnings=projection_warnings
    )


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--scan-dir", required=True, type=Path)
    parser.add_argument("--schema-dir", type=Path)
    parser.add_argument("--source-root", type=Path)
    parser.add_argument("--sarif-only", action="store_true")
    parser.add_argument("--sarif-output", type=Path)
    parser.add_argument(
        "--export-artifact", choices=("findings", "threat-model"), default="findings"
    )
    parser.add_argument("--export-format", choices=[*sorted(EXPORT_PATHS), "md"])
    parser.add_argument("--avit-template", type=Path)
    parser.add_argument("--export-output", type=Path)
    parser.add_argument("--no-clobber", action="store_true")
    parser.add_argument("--export-metadata", action="store_true")
    parser.add_argument("--describe-threat-model", action="store_true")
    parser.add_argument("--write-threat-model", action="store_true")
    args = parser.parse_args()
    try:
        args.scan_dir = args.scan_dir.resolve()
        if args.avit_template is not None:
            if args.export_format != "servicenow-avit":
                parser.error(
                    "--avit-template is only supported with --export-format servicenow-avit"
                )
            if (
                args.export_output
                and args.export_output.exists()
                and args.avit_template.exists()
                and args.export_output.samefile(args.avit_template)
            ):
                parser.error("AVIT export output cannot overwrite the reusable template")
        if args.describe_threat_model:
            sys.stdout.buffer.write(
                _json_bytes(describe_threat_model(args.scan_dir, args.schema_dir))
            )
            return 0
        if args.write_threat_model:
            write_threat_model_projection_if_possible(args.scan_dir)
            return 0
        if args.export_artifact == "threat-model" and args.export_format is None:
            args.export_format = "md"
        if args.export_metadata and (
            args.export_artifact != "threat-model" or args.export_output is None
        ):
            parser.error("--export-metadata requires a threat-model export with --export-output")
        if args.sarif_only and args.export_format is not None:
            parser.error("--sarif-only cannot be combined with --export-format")
        if args.export_output is not None and args.export_format is None:
            parser.error("--export-output requires --export-format")
        if args.sarif_output is not None and not args.sarif_only:
            parser.error("--sarif-output requires --sarif-only")
        if args.sarif_only:
            args.export_format, args.export_output = "sarif", args.sarif_output
        if args.export_format is not None:
            if args.export_artifact == "threat-model":
                if args.export_format != "md":
                    parser.error("threat-model exports require --export-format md")
                if args.source_root is not None:
                    parser.error("source-root is only supported for SARIF exports")
                saved = _read_saved_threat_model(args.scan_dir, schema_dir=args.schema_dir)
                if saved is None:
                    raise ContractError("No saved threat model is available for this result.")
                description, contents = saved
            else:
                contents = build_findings_export(
                    args.scan_dir,
                    args.export_format,
                    args.source_root,
                    args.schema_dir,
                    avit_template=args.avit_template,
                )
            if args.export_output is None:
                sys.stdout.buffer.write(contents)
            else:
                try:
                    write_export_output(
                        args.scan_dir,
                        args.export_output,
                        args.export_format,
                        contents,
                        replace_existing=not args.no_clobber,
                    )
                except FileExistsError:
                    if not args.no_clobber:
                        raise
                    raise ContractError(
                        f"{args.export_output} already exists. Use --output FILE to choose or replace a file."
                    ) from None
                if args.export_metadata:
                    sys.stdout.buffer.write(
                        _json_bytes({**description, "path": str(args.export_output.absolute())})
                    )
        else:
            finalize_scan(args.scan_dir, args.schema_dir, args.source_root)
    except (ContractError, OSError) as exc:
        # Keep canonical paths readable and escape control characters at the terminal boundary.
        parser.error(
            "".join(char if char.isprintable() else ascii(char)[1:-1] for char in str(exc))
        )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

SHA-256: 339d9f2068634e65147373fe87b4a88c44d4f17d3e36fa06c0fcb3e97b66f8da