release/v1/scripts/build_release.py

#!/usr/bin/env python3
"""Build a curated, integrity-checked public reproduction bundle.

The release intentionally excludes upstream repositories, third-party model
weights, virtual environments, caches, and append-heavy raw records. Valid raw
records remain in the public evidence Bucket; this bundle carries their exact
manifests, input snapshots, hashes, URLs, and newly trained JSON checkpoints.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import shutil
import tempfile
from pathlib import Path
from typing import Any, Iterable, Mapping, Sequence

from build_tables import (
    BatchData,
    ValidationError as EvidenceValidationError,
    load_batch,
    validate_cross_batch_identity,
)
from make_figures import (
    ValidationError as FigureValidationError,
    read_verified_tables,
)


PUBLIC_BUCKET_URL = (
    "https://huggingface.co/buckets/JacobLinCool/chebyshev-job-artifacts"
)
HF_NAMESPACE = "JacobLinCool"
EXPECTED_PAPER_VERSION = "2605.22305v4"
EXPECTED_OPENREVIEW_ID = "aNWIVNjocB"
PUBLIC_RUNNER_URL_TEMPLATE = (
    f"{PUBLIC_BUCKET_URL}/resolve/input/{{version}}/run_reproduction.py"
)
EXPECTED_JOB_VERSIONS = ("v2", "v3", "v4")
EXPECTED_JOB_SCOPES = ("claims23", "claim4", "claim5")
EXPECTED_JOB_CONFIGS = {
    "claims23": "claim23_full.json",
    "claim4": "claim4_full.json",
    "claim5": "claim5_pendulum_full.json",
}
EXPECTED_RUNNER_SHA256 = {
    "v2": "0145c1407229d1502ecf5e1d9b67e31d8c1ea7a1d04afda03e91a0d209fcc29e",
    "v3": "62dc9f671b106da9e49fe2d4e6095e1432df7472f089c4b48781f789c58884e6",
    "v4": "62dc9f671b106da9e49fe2d4e6095e1432df7472f089c4b48781f789c58884e6",
}
EXPECTED_CONFIG_SHA256 = {
    "claims23": "b329a0d6457b17e63512cbad638dad3099536ac5a5f97cf93bfa84a138c5d196",
    "claim4": "ddfbae3fd5fbb3e30d77ec53776b16358875802e75e9019ce3eb4149c6567734",
    "claim5": "0aee46522d9005864074794094ef77e279f271e97dc84dac075b924a3506f3e0",
}
EXPECTED_LOCK_SHA256 = (
    "939e6cc01415baf184916008bddea01846be182ce8c109e3ca457f06a1a7a09f"
)
EXPECTED_SPEC_SHA256 = (
    "e1bbedcbcc85375bc8a8bf979b05b18d9ddabb7b57aa785e353863e9fdcb145a"
)
EXPECTED_BATCH_PROFILES = {
    "claims23": "full_claims_2_3",
    "claim4": "full_claim_4",
    "claim5": "full_claim_5_pendulum",
}
EXPECTED_HISTORICAL_OUTCOMES = {
    ("v2", "claims23"): ("ERROR", "failed"),
    ("v2", "claim4"): ("CANCELED", "canceled"),
    ("v2", "claim5"): ("CANCELED", "canceled"),
    ("v3", "claims23"): ("COMPLETED", "rejected"),
    ("v3", "claim4"): ("CANCELED", "canceled"),
    ("v3", "claim5"): ("CANCELED", "canceled"),
}
EXPECTED_FIGURE_KEYS = {
    "mountaincar_return_vs_start",
    "mountaincar_seed_distribution",
    "parameter_performance_comparison",
    "pendulum_heatmap_difference",
}
EXPECTED_POSTER_FILES = {
    "poster.html": "poster_html",
    "poster_embed.html": "poster_embed_html",
    "poster_preview.png": "poster_preview_png",
    "poster_preview.pdf": "poster_preview_pdf",
    "GATE_REPORT.json": "gate_report",
    "style_check.json": "gate_report",
    "asset_check.json": "gate_report",
}
REQUIRED_README_HEADINGS = (
    "Executive summary",
    "Claim-by-claim verdicts",
    "How to reproduce",
    "Evidence and provenance",
    "Interactive reports",
    "Limitations",
)

BLOCKED_PARTS = {
    ".cache",
    ".git",
    ".pytest_cache",
    ".ruff_cache",
    ".venv",
    "__pycache__",
    "tensorboard_logs",
}
IGNORED_SUFFIXES = {".pyc", ".pyo"}
SENSITIVE_FILENAMES = {
    ".env",
    ".netrc",
    ".npmrc",
    ".pypirc",
    "credentials",
    "credentials.json",
    "id_dsa",
    "id_ecdsa",
    "id_ed25519",
    "id_rsa",
}
SENSITIVE_SUFFIXES = {
    ".key",
    ".p12",
    ".pfx",
    ".pem",
}
MODEL_WEIGHT_SUFFIXES = {
    ".bin",
    ".ckpt",
    ".h5",
    ".joblib",
    ".npy",
    ".npz",
    ".onnx",
    ".pickle",
    ".pkl",
    ".pt",
    ".pth",
    ".safetensors",
    ".zip",
}
PLACEHOLDER_PATTERN = re.compile(r"__[A-Z][A-Z0-9_]*__")
SHA256_PATTERN = re.compile(r"[0-9a-f]{64}")
HF_JOB_ID_PATTERN = re.compile(r"[0-9a-f]{24}")
SECRET_CONTENT_PATTERNS = (
    (re.compile(rb"hf_[A-Za-z0-9]{20,}"), "Hugging Face token"),
    (
        re.compile(rb"-----BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY-----"),
        "private key",
    ),
    (
        re.compile(rb"(?i)(?:HF_TOKEN|HUGGING_FACE_HUB_TOKEN)\s*=\s*[^\s\"']+"),
        "Hugging Face token assignment",
    ),
)


class ReleaseError(RuntimeError):
    """Raised when a source cannot enter the public bundle safely."""


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _reject_json_constant(value: str) -> None:
    raise ReleaseError(f"Non-standard JSON constant is forbidden: {value}")


def _unique_json_object(pairs: Sequence[tuple[str, Any]]) -> dict[str, Any]:
    output: dict[str, Any] = {}
    for key, value in pairs:
        if key in output:
            raise ReleaseError(f"Duplicate JSON object key: {key!r}")
        output[key] = value
    return output


def load_json_object(path: Path) -> dict[str, Any]:
    try:
        value = json.loads(
            path.read_text(encoding="utf-8"),
            object_pairs_hook=_unique_json_object,
            parse_constant=_reject_json_constant,
        )
    except (OSError, json.JSONDecodeError, ReleaseError) as error:
        raise ReleaseError(f"Cannot read JSON object {path}: {error}") from error
    if not isinstance(value, dict):
        raise ReleaseError(f"Expected a JSON object in {path}")
    return value


def require_real_file(path: Path) -> Path:
    resolved = path.resolve()
    if not resolved.is_file() or path.is_symlink():
        raise ReleaseError(f"Expected a real file: {path}")
    return resolved


def require_real_directory(path: Path) -> Path:
    resolved = path.resolve()
    if not resolved.is_dir() or path.is_symlink():
        raise ReleaseError(f"Expected a real directory: {path}")
    return resolved


def require_sha256(value: Any, label: str) -> str:
    if not isinstance(value, str) or SHA256_PATTERN.fullmatch(value) is None:
        raise ReleaseError(f"{label} is not a lowercase SHA-256 digest")
    return value


def require_exact_keys(
    value: Mapping[str, Any], expected: set[str], label: str
) -> None:
    actual = set(value)
    if actual != expected:
        raise ReleaseError(
            f"{label} keys mismatch; extra={sorted(actual - expected)}, "
            f"missing={sorted(expected - actual)}"
        )


def require_nonempty_string(value: Any, label: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise ReleaseError(f"{label} must be a nonempty string")
    return value


def require_nonnegative_number_or_none(value: Any, label: str) -> float | None:
    if value is None:
        return None
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise ReleaseError(f"{label} must be a nonnegative number or null")
    number = float(value)
    if not (number >= 0 and number < float("inf")):
        raise ReleaseError(f"{label} must be a finite nonnegative number")
    return number


def validate_builder_provenance(
    manifest: Mapping[str, Any],
    *,
    script_path: Path,
    expected_command_without_replace: Sequence[str],
    label: str,
) -> None:
    expected_hash = sha256_file(require_real_file(script_path))
    if manifest.get("builder_sha256") != expected_hash:
        raise ReleaseError(f"{label} builder SHA does not match the current script")
    command = manifest.get("command")
    if not isinstance(command, list) or any(
        not isinstance(argument, str) or not argument for argument in command
    ):
        raise ReleaseError(f"{label} command must be an argv list of nonempty strings")
    expected = list(expected_command_without_replace)
    if command not in (expected, [*expected, "--replace"]):
        raise ReleaseError(
            f"{label} command does not match the current resolved inputs and output"
        )


def safe_relative_path(value: Any, label: str) -> Path:
    parts = value.split("/") if isinstance(value, str) else []
    if (
        not isinstance(value, str)
        or not value
        or "\\" in value
        or value.startswith("/")
        or any(part in {"", ".", ".."} for part in parts)
    ):
        raise ReleaseError(f"Unsafe {label}: {value!r}")
    path = Path(*parts)
    reject_sensitive_path(path, label)
    return path


def is_ignored(relative_path: Path) -> bool:
    return any(part in BLOCKED_PARTS for part in relative_path.parts) or (
        relative_path.suffix.lower() in IGNORED_SUFFIXES
    )


def reject_sensitive_path(path: Path, label: str) -> None:
    name = path.name.lower()
    suffix = path.suffix.lower()
    if (
        name in SENSITIVE_FILENAMES
        or name.startswith(".env.")
        or suffix in SENSITIVE_SUFFIXES
    ):
        raise ReleaseError(f"Secret-bearing path is forbidden in {label}: {path}")
    if suffix in MODEL_WEIGHT_SUFFIXES:
        raise ReleaseError(f"Model-weight/archive path is forbidden in {label}: {path}")


def copy_file(source: Path, destination: Path) -> None:
    real_source = require_real_file(source)
    destination.parent.mkdir(parents=True, exist_ok=True)
    if destination.exists():
        raise ReleaseError(f"Duplicate release destination: {destination}")
    shutil.copy2(real_source, destination)


def copy_tree(
    source: Path,
    destination: Path,
    *,
    allowed_suffixes: set[str] | None = None,
) -> int:
    real_source = require_real_directory(source)
    copied = 0
    for candidate in sorted(real_source.rglob("*")):
        relative = candidate.relative_to(real_source)
        if is_ignored(relative):
            continue
        if candidate.is_symlink():
            raise ReleaseError(
                f"Symlink is not allowed in release sources: {candidate}"
            )
        if candidate.is_dir():
            continue
        if not candidate.is_file():
            raise ReleaseError(f"Unsupported filesystem entry: {candidate}")
        reject_sensitive_path(relative, str(source))
        if (
            allowed_suffixes is not None
            and relative.suffix.lower() not in allowed_suffixes
        ):
            raise ReleaseError(f"Unexpected file type in {source}: {relative}")
        copy_file(candidate, destination / relative)
        copied += 1
    if copied == 0:
        raise ReleaseError(f"Refusing to copy an empty tree: {source}")
    return copied


def exact_file_inventory(root: Path, expected: Iterable[Path], label: str) -> None:
    real_root = require_real_directory(root)
    expected_set = {path.as_posix() for path in expected}
    actual: set[str] = set()
    for candidate in sorted(real_root.rglob("*")):
        relative = candidate.relative_to(real_root)
        if candidate.is_symlink():
            raise ReleaseError(f"Symlink is not allowed in {label}: {candidate}")
        if candidate.is_dir():
            continue
        if not candidate.is_file():
            raise ReleaseError(f"Unsupported filesystem entry in {label}: {candidate}")
        reject_sensitive_path(relative, label)
        actual.add(relative.as_posix())
    if actual != expected_set:
        raise ReleaseError(
            f"{label} file inventory mismatch; extra={sorted(actual - expected_set)}, "
            f"missing={sorted(expected_set - actual)}"
        )


def copy_verified_files(
    source: Path, destination: Path, relative_paths: Iterable[Path]
) -> None:
    for relative in sorted(relative_paths, key=lambda path: path.as_posix()):
        copy_file(source / relative, destination / relative)


def paths_overlap(first: Path, second: Path) -> bool:
    return first == second or first in second.parents or second in first.parents


def validate_source_destination_disjoint(
    output_root: Path, source_paths: Iterable[Path]
) -> None:
    destination = output_root.resolve()
    for source_path in source_paths:
        source = source_path.resolve()
        if paths_overlap(destination, source):
            raise ReleaseError(
                f"Release output and source must be disjoint: {destination} vs {source}"
            )


def load_validated_batches(
    raw_roots: Sequence[Path], runner_path: Path
) -> list[BatchData]:
    runner_hash = sha256_file(require_real_file(runner_path))
    try:
        batches = [load_batch(require_real_directory(root)) for root in raw_roots]
        validate_cross_batch_identity(batches)
    except EvidenceValidationError as error:
        raise ReleaseError(f"Raw evidence validation failed: {error}") from error
    for batch in batches:
        manifest = batch.manifest
        if manifest.get("runner_sha256") != runner_hash:
            raise ReleaseError(
                f"Local runner does not match raw manifest for {batch.directory}"
            )
        if manifest.get("paper_version") != EXPECTED_PAPER_VERSION:
            raise ReleaseError(f"Unexpected paper version in {batch.directory}")
        if manifest.get("openreview_id") != EXPECTED_OPENREVIEW_ID:
            raise ReleaseError(f"Unexpected OpenReview id in {batch.directory}")
    return sorted(batches, key=lambda batch: str(batch.manifest["batch_id"]))


def validated_batches_by_scope(
    batches: Sequence[BatchData],
) -> dict[str, BatchData]:
    by_scope: dict[str, BatchData] = {}
    profile_to_scope = {
        profile: scope for scope, profile in EXPECTED_BATCH_PROFILES.items()
    }
    for batch in batches:
        config = batch.manifest.get("config")
        profile = config.get("profile") if isinstance(config, dict) else None
        scope = profile_to_scope.get(profile)
        if scope is None:
            raise ReleaseError(
                f"Validated v4 batch has an unexpected config profile: {profile!r}"
            )
        if scope in by_scope:
            raise ReleaseError(f"Duplicate validated v4 batch for scope {scope}")
        by_scope[scope] = batch
    if set(by_scope) != set(EXPECTED_JOB_SCOPES):
        raise ReleaseError(
            "Validated raw batches must cover exactly claims23, claim4, and claim5; "
            f"actual={sorted(by_scope)}"
        )
    return by_scope


def validate_job_hardware(value: Any, label: str) -> None:
    if not isinstance(value, dict):
        raise ReleaseError(f"{label} must be an object")
    expected = {
        "flavor": "t4-medium",
        "cpu_count": 8,
        "memory_gb": 30,
        "storage_gb": 100,
        "accelerator": "NVIDIA T4 16GB",
    }
    require_exact_keys(value, set(expected), label)
    if value != expected:
        raise ReleaseError(f"{label} does not describe the required t4-medium hardware")


def validate_job_durations(value: Any, *, label: str, canceled: bool) -> None:
    if not isinstance(value, dict):
        raise ReleaseError(f"{label} must be an object")
    keys = {"scheduling_seconds", "running_seconds", "total_seconds"}
    require_exact_keys(value, keys, label)
    scheduling = require_nonnegative_number_or_none(
        value["scheduling_seconds"], f"{label}.scheduling_seconds"
    )
    running = require_nonnegative_number_or_none(
        value["running_seconds"], f"{label}.running_seconds"
    )
    total = require_nonnegative_number_or_none(
        value["total_seconds"], f"{label}.total_seconds"
    )
    if canceled:
        if any(item is not None for item in (scheduling, running, total)):
            raise ReleaseError(
                f"{label} must use null durations for a canceled attempt"
            )
        return
    if any(item is None for item in (scheduling, running, total)):
        raise ReleaseError(f"{label} requires complete durations for this attempt")
    assert scheduling is not None and running is not None and total is not None
    if abs(total - (scheduling + running)) > 5:
        raise ReleaseError(f"{label}.total_seconds disagrees with its components")


def validate_scheduler_command(
    value: Any,
    *,
    version: str,
    scope: str,
    batch_id: str | None,
    label: str,
) -> list[str]:
    if (
        not isinstance(value, list)
        or not value
        or any(not isinstance(argument, str) or not argument for argument in value)
    ):
        raise ReleaseError(f"{label} must be a nonempty argv list")
    config = EXPECTED_JOB_CONFIGS[scope]
    if not any(config in argument for argument in value):
        raise ReleaseError(f"{label} does not identify its scope config")
    if version == "v4":
        expected = [
            "bash",
            "/artifacts/input/v4/run_hf_job.sh",
            config,
            require_nonempty_string(batch_id, f"{label} batch id"),
        ]
        if value != expected:
            raise ReleaseError(
                f"{label} does not match the inspected v4 scheduler argv"
            )
    elif (
        len(value) < 3
        or Path(value[0]).name != "uv"
        or value[1] != "run"
        or not any("run_reproduction.py" in argument for argument in value[2:])
    ):
        raise ReleaseError(
            f"{label} does not match the inspected {version} uv-run scheduler argv"
        )
    return value


def validate_job_input_hashes(
    value: Any, *, version: str, scope: str, label: str
) -> dict[str, str]:
    if not isinstance(value, dict):
        raise ReleaseError(f"{label} must be an object")
    require_exact_keys(value, {"runner", "config", "lock", "spec"}, label)
    expected = {
        "runner": EXPECTED_RUNNER_SHA256[version],
        "config": EXPECTED_CONFIG_SHA256[scope],
        "lock": EXPECTED_LOCK_SHA256,
        "spec": EXPECTED_SPEC_SHA256,
    }
    for name, digest in value.items():
        require_sha256(digest, f"{label}.{name}")
    if value != expected:
        raise ReleaseError(f"{label} does not match the audited public inputs")
    return value


def validate_reproduction_command(
    value: Any,
    *,
    version: str,
    scope: str,
    required_hashes: Iterable[str],
    label: str,
) -> list[str]:
    if (
        not isinstance(value, list)
        or not value
        or any(not isinstance(argument, str) or not argument for argument in value)
    ):
        raise ReleaseError(f"{label} must be a nonempty argv list")
    is_bash_recipe = len(value) == 3 and value[:2] == ["bash", "-lc"]
    is_hf_recipe = len(value) >= 4 and value[:3] == ["hf", "jobs", "run"]
    if not (is_bash_recipe or is_hf_recipe):
        raise ReleaseError(
            f"{label} must be a bash -lc recipe or a concrete hf jobs run argv"
        )
    command_text = "\n".join(value)
    input_base = f"{PUBLIC_BUCKET_URL}/resolve/input/{version}"
    expected_urls = {
        f"{input_base}/run_reproduction.py",
        f"{input_base}/{EXPECTED_JOB_CONFIGS[scope]}",
        f"{input_base}/upstream.lock.json",
        f"{input_base}/SPEC.md",
    }
    missing_urls = sorted(url for url in expected_urls if url not in command_text)
    if missing_urls:
        raise ReleaseError(f"{label} is missing immutable input URLs: {missing_urls}")
    if "set -euo pipefail" not in command_text:
        raise ReleaseError(f"{label} must fail closed with set -euo pipefail")
    if "curl" not in command_text or not re.search(
        r"(?:curl\s+(?:[^\n;]*\s)?-f|curl\s+(?:[^\n;]*\s)?--fail)", command_text
    ):
        raise ReleaseError(f"{label} must download inputs with fail-on-HTTP-error curl")
    has_sha_tool = "sha256sum" in command_text or "shasum -a 256" in command_text
    digests = set(SHA256_PATTERN.findall(command_text))
    if not has_sha_tool or len(digests) < 4:
        raise ReleaseError(
            f"{label} must verify all four immutable inputs with SHA-256"
        )
    missing_hashes = set(required_hashes) - digests
    if missing_hashes:
        raise ReleaseError(
            f"{label} is missing validated v4 input hashes: {sorted(missing_hashes)}"
        )
    required_invocation_tokens = ("uv run", "--config", "--lock-path", "--spec-path")
    if any(token not in command_text for token in required_invocation_tokens):
        raise ReleaseError(
            f"{label} does not contain a complete executable runner invocation"
        )
    return value


def validate_jobs_root(
    jobs_root: Path,
    batches: Sequence[BatchData],
    runner_path: Path,
) -> tuple[dict[str, Any], tuple[Path, ...]]:
    root = require_real_directory(jobs_root)
    inventory = (Path("HF_JOBS.json"),)
    exact_file_inventory(root, inventory, "Hugging Face Jobs inventory")
    manifest = load_json_object(require_real_file(root / inventory[0]))
    require_exact_keys(
        manifest,
        {"schema_version", "paper", "evidence_bucket_url", "runner", "attempts"},
        "HF_JOBS.json",
    )
    if manifest["schema_version"] != "1.0.0":
        raise ReleaseError("Unsupported HF_JOBS.json schema_version")
    paper = manifest["paper"]
    if not isinstance(paper, dict):
        raise ReleaseError("HF_JOBS.json paper must be an object")
    require_exact_keys(paper, {"openreview_id", "arxiv_version"}, "jobs paper")
    if paper != {
        "openreview_id": EXPECTED_OPENREVIEW_ID,
        "arxiv_version": EXPECTED_PAPER_VERSION,
    }:
        raise ReleaseError("HF_JOBS.json paper identity mismatch")
    if manifest["evidence_bucket_url"] != PUBLIC_BUCKET_URL:
        raise ReleaseError("HF_JOBS.json evidence Bucket URL mismatch")
    runner = manifest["runner"]
    if not isinstance(runner, dict):
        raise ReleaseError("HF_JOBS.json runner must be an object")
    require_exact_keys(runner, {"url", "sha256"}, "jobs runner")
    if runner["url"] != PUBLIC_RUNNER_URL_TEMPLATE.format(version="v4"):
        raise ReleaseError("HF_JOBS.json v4 runner URL mismatch")
    if runner["sha256"] != sha256_file(require_real_file(runner_path)):
        raise ReleaseError("HF_JOBS.json runner SHA does not match the local runner")

    attempts = manifest["attempts"]
    if not isinstance(attempts, list) or len(attempts) != 9:
        raise ReleaseError("HF_JOBS.json must contain exactly nine attempts")
    by_scope = validated_batches_by_scope(batches)
    seen_pairs: set[tuple[str, str]] = set()
    seen_job_ids: set[str] = set()
    for index, attempt in enumerate(attempts):
        label = f"jobs attempt {index}"
        if not isinstance(attempt, dict):
            raise ReleaseError(f"{label} must be an object")
        require_exact_keys(
            attempt,
            {
                "version",
                "scope",
                "job_id",
                "job_url",
                "status",
                "disposition",
                "disposition_reason",
                "scheduler_command",
                "reproduction_command",
                "input_sha256",
                "hardware",
                "durations",
                "cost_usd",
                "peak_rss_mb",
                "batch",
            },
            label,
        )
        version = attempt["version"]
        scope = attempt["scope"]
        if version not in EXPECTED_JOB_VERSIONS or scope not in EXPECTED_JOB_SCOPES:
            raise ReleaseError(f"{label} has an unexpected version/scope")
        pair = (version, scope)
        if pair in seen_pairs:
            raise ReleaseError(f"Duplicate HF Job attempt for {version}/{scope}")
        seen_pairs.add(pair)
        job_id = attempt["job_id"]
        if not isinstance(job_id, str) or HF_JOB_ID_PATTERN.fullmatch(job_id) is None:
            raise ReleaseError(f"{label}.job_id is invalid")
        if job_id in seen_job_ids:
            raise ReleaseError(f"Duplicate HF Job id: {job_id}")
        seen_job_ids.add(job_id)
        expected_job_url = f"https://huggingface.co/jobs/{HF_NAMESPACE}/{job_id}"
        if attempt["job_url"] != expected_job_url:
            raise ReleaseError(f"{label}.job_url does not match its job id")

        raw_batch = by_scope[scope] if version == "v4" else None
        raw_batch_id = (
            str(raw_batch.manifest["batch_id"]) if raw_batch is not None else None
        )
        input_hashes = validate_job_input_hashes(
            attempt["input_sha256"],
            version=version,
            scope=scope,
            label=f"{label}.input_sha256",
        )
        scheduler_command = validate_scheduler_command(
            attempt["scheduler_command"],
            version=version,
            scope=scope,
            batch_id=raw_batch_id,
            label=f"{label}.scheduler_command",
        )
        reproduction_command = validate_reproduction_command(
            attempt["reproduction_command"],
            version=version,
            scope=scope,
            required_hashes=input_hashes.values(),
            label=f"{label}.reproduction_command",
        )
        if scheduler_command == reproduction_command:
            raise ReleaseError(
                f"{label} scheduler and reproduction commands must remain distinct"
            )

        validate_job_hardware(attempt["hardware"], f"{label}.hardware")
        status = attempt["status"]
        disposition = attempt["disposition"]
        if version == "v4":
            expected_status, expected_disposition = "COMPLETED", "validated"
        else:
            expected_status, expected_disposition = EXPECTED_HISTORICAL_OUTCOMES[pair]
        if (status, disposition) != (expected_status, expected_disposition):
            raise ReleaseError(
                f"{label} historical status/disposition does not match the audited attempt"
            )
        reason = require_nonempty_string(
            attempt["disposition_reason"], f"{label}.disposition_reason"
        )
        if len(reason.split()) < 3:
            raise ReleaseError(f"{label}.disposition_reason is not meaningful")
        canceled = status == "CANCELED"
        validate_job_durations(
            attempt["durations"], label=f"{label}.durations", canceled=canceled
        )
        cost = require_nonnegative_number_or_none(
            attempt["cost_usd"], f"{label}.cost_usd"
        )
        if canceled != (cost is None):
            raise ReleaseError(
                f"{label}.cost_usd must be null exactly for canceled attempts"
            )
        peak_rss = require_nonnegative_number_or_none(
            attempt["peak_rss_mb"], f"{label}.peak_rss_mb"
        )
        if version != "v4":
            if peak_rss is not None:
                raise ReleaseError(f"{label}.peak_rss_mb must be null for v2/v3")
        else:
            assert raw_batch is not None
            raw_peak_rss = require_nonnegative_number_or_none(
                raw_batch.manifest.get("peak_rss_mb"),
                f"{label} raw manifest peak_rss_mb",
            )
            if raw_peak_rss is None or peak_rss != raw_peak_rss:
                raise ReleaseError(
                    f"{label}.peak_rss_mb does not match the raw batch manifest"
                )
            raw_inputs = raw_batch.manifest.get("input_hashes")
            expected_raw_inputs = {
                "SPEC.md": input_hashes["spec"],
                EXPECTED_JOB_CONFIGS[scope]: input_hashes["config"],
                "upstream.lock.json": input_hashes["lock"],
            }
            if raw_inputs != expected_raw_inputs:
                raise ReleaseError(
                    f"{label}.input_sha256 does not match the raw batch manifest"
                )
            if raw_batch.manifest.get("runner_sha256") != input_hashes["runner"]:
                raise ReleaseError(
                    f"{label}.input_sha256 runner does not match the raw batch manifest"
                )

        batch_declaration = attempt["batch"]
        if version != "v4":
            if batch_declaration is not None:
                raise ReleaseError(
                    f"{label} historical attempt must not declare a batch"
                )
            continue
        if not isinstance(batch_declaration, dict):
            raise ReleaseError(f"{label} validated attempt must declare its batch")
        require_exact_keys(
            batch_declaration,
            {"batch_id", "manifest_sha256", "records_sha256", "evidence_url"},
            f"{label}.batch",
        )
        assert raw_batch is not None
        batch = raw_batch
        batch_id = str(batch.manifest["batch_id"])
        expected_batch = {
            "batch_id": batch_id,
            "manifest_sha256": batch.manifest_sha256,
            "records_sha256": batch.records_sha256,
            "evidence_url": f"{PUBLIC_BUCKET_URL}/tree/raw/{batch_id}",
        }
        if batch_declaration != expected_batch:
            raise ReleaseError(f"{label}.batch does not match validated raw evidence")
        if extract_job_id(batch.manifest) != job_id:
            raise ReleaseError(f"{label}.job_id does not match the raw batch manifest")

    expected_pairs = {
        (version, scope)
        for version in EXPECTED_JOB_VERSIONS
        for scope in EXPECTED_JOB_SCOPES
    }
    if seen_pairs != expected_pairs:
        raise ReleaseError("HF_JOBS.json does not contain the exact attempt matrix")
    return manifest, inventory


def validate_tables_root(
    tables_root: Path,
    batches: Sequence[BatchData],
    *,
    builder_script: Path,
    raw_roots: Sequence[Path],
) -> tuple[dict[str, Any], tuple[Path, ...]]:
    root = require_real_directory(tables_root)
    try:
        manifest, _ = read_verified_tables(root)
    except FigureValidationError as error:
        raise ReleaseError(f"Canonical table validation failed: {error}") from error

    command = [str(builder_script.resolve())]
    for raw_root in raw_roots:
        command.extend(("--raw-root", str(raw_root.resolve())))
    command.extend(("--output-root", str(root)))
    validate_builder_provenance(
        manifest,
        script_path=builder_script,
        expected_command_without_replace=command,
        label="Canonical tables",
    )

    source_batches = manifest.get("source_batches")
    if not isinstance(source_batches, list):
        raise ReleaseError("Canonical table manifest has no source_batches list")
    expected = {str(batch.manifest["batch_id"]): batch for batch in batches}
    actual: dict[str, Mapping[str, Any]] = {}
    for entry in source_batches:
        if not isinstance(entry, dict) or not isinstance(entry.get("batch_id"), str):
            raise ReleaseError("Canonical table manifest has an invalid source batch")
        batch_id = entry["batch_id"]
        if batch_id in actual:
            raise ReleaseError(f"Duplicate canonical source batch: {batch_id}")
        actual[batch_id] = entry
    if set(actual) != set(expected):
        raise ReleaseError(
            "Canonical table/raw batch provenance mismatch; "
            f"tables={sorted(actual)}, raw={sorted(expected)}"
        )
    for batch_id, batch in expected.items():
        entry = actual[batch_id]
        if entry.get("manifest_sha256") != batch.manifest_sha256:
            raise ReleaseError(f"Canonical manifest SHA mismatch for {batch_id}")
        if entry.get("records_sha256") != batch.records_sha256:
            raise ReleaseError(f"Canonical records SHA mismatch for {batch_id}")
        if entry.get("record_counts") != batch.manifest.get("record_counts"):
            raise ReleaseError(f"Canonical record-count mismatch for {batch_id}")

    identity = batches[0].manifest
    for key in (
        "experiment_id",
        "spec_version",
        "paper_version",
        "openreview_id",
    ):
        if manifest.get(key) != identity.get(key):
            raise ReleaseError(f"Canonical table identity mismatch for {key}")
    declared_tables = manifest["tables"]
    paths = tuple(
        safe_relative_path(declaration["path"], f"table {name} path")
        for name, declaration in sorted(declared_tables.items())
    )
    inventory = (Path("MANIFEST.json"), *paths)
    exact_file_inventory(root, inventory, "canonical tables")
    return manifest, inventory


def validate_declared_output(
    root: Path, declaration: Any, label: str, *, default_path: str | None = None
) -> Path:
    if not isinstance(declaration, dict):
        raise ReleaseError(f"Invalid file declaration for {label}")
    raw_path = declaration.get("path", default_path)
    relative = safe_relative_path(raw_path, f"{label} path")
    path = require_real_file(root / relative)
    expected_hash = require_sha256(declaration.get("sha256"), f"{label}.sha256")
    expected_bytes = declaration.get("bytes")
    if isinstance(expected_bytes, bool) or not isinstance(expected_bytes, int):
        raise ReleaseError(f"{label}.bytes must be an integer")
    if expected_bytes < 0 or path.stat().st_size != expected_bytes:
        raise ReleaseError(f"Declared byte count mismatch for {label}")
    if sha256_file(path) != expected_hash:
        raise ReleaseError(f"Declared SHA-256 mismatch for {label}")
    return relative


def table_hashes(manifest: Mapping[str, Any]) -> dict[str, str]:
    return {
        name: require_sha256(declaration.get("sha256"), f"table {name}.sha256")
        for name, declaration in sorted(manifest["tables"].items())
    }


def validate_analysis_root(
    analysis_root: Path,
    tables_root: Path,
    tables_manifest: Mapping[str, Any],
    *,
    builder_script: Path,
) -> tuple[Path, ...]:
    root = require_real_directory(analysis_root)
    manifest_path = require_real_file(root / "MANIFEST.json")
    manifest = load_json_object(manifest_path)
    validate_builder_provenance(
        manifest,
        script_path=builder_script,
        expected_command_without_replace=(
            str(builder_script.resolve()),
            "--tables-root",
            str(tables_root.resolve()),
            "--output-root",
            str(root),
        ),
        label="Analysis",
    )
    if manifest.get("status") != "success":
        raise ReleaseError("Analysis manifest is not successful")
    expected_manifest_hash = sha256_file(tables_root / "MANIFEST.json")
    if manifest.get("source_tables_manifest_sha256") != expected_manifest_hash:
        raise ReleaseError("Analysis points to a different canonical table manifest")
    if manifest.get("source_table_hashes") != table_hashes(tables_manifest):
        raise ReleaseError("Analysis table-hash provenance mismatch")
    outputs = manifest.get("outputs")
    if not isinstance(outputs, dict) or not outputs:
        raise ReleaseError("Analysis manifest has no declared outputs")
    paths = tuple(
        validate_declared_output(
            root, declaration, f"analysis {name}", default_path=name
        )
        for name, declaration in sorted(outputs.items())
    )
    inventory = (Path("MANIFEST.json"), *paths)
    exact_file_inventory(root, inventory, "analysis outputs")
    return inventory


def validate_reports_root(
    reports_root: Path,
    tables_root: Path,
    tables_manifest: Mapping[str, Any],
    *,
    builder_script: Path,
) -> tuple[Path, ...]:
    root = require_real_directory(reports_root)
    manifest = load_json_object(require_real_file(root / "MANIFEST.json"))
    validate_builder_provenance(
        manifest,
        script_path=builder_script,
        expected_command_without_replace=(
            str(builder_script.resolve()),
            "--tables-root",
            str(tables_root.resolve()),
            "--output-root",
            str(root),
        ),
        label="Interactive reports",
    )
    if manifest.get("status") != "success":
        raise ReleaseError("Interactive-report manifest is not successful")
    source = manifest.get("source")
    if not isinstance(source, dict):
        raise ReleaseError("Interactive-report manifest has no source object")
    if source.get("tables_manifest_sha256") != sha256_file(
        tables_root / "MANIFEST.json"
    ):
        raise ReleaseError("Interactive reports point to different canonical tables")
    if source.get("table_hashes") != table_hashes(tables_manifest):
        raise ReleaseError("Interactive-report table-hash provenance mismatch")
    figures = manifest.get("figures")
    if not isinstance(figures, dict) or not figures:
        raise ReleaseError("Interactive-report manifest has no figures")
    missing_keys = EXPECTED_FIGURE_KEYS - set(figures)
    if missing_keys:
        raise ReleaseError(
            f"Interactive-report manifest is missing required figures: {sorted(missing_keys)}"
        )
    declared_paths: list[Path] = []
    for name, entry in sorted(figures.items()):
        if not isinstance(entry, dict):
            raise ReleaseError(f"Invalid interactive-report entry: {name}")
        status = entry.get("status")
        if name in EXPECTED_FIGURE_KEYS and status != "generated":
            raise ReleaseError(f"Required interactive figure {name} was not generated")
        if status == "generated":
            declared_paths.append(
                validate_declared_output(root, entry.get("html"), f"figure {name} HTML")
            )
            declared_paths.append(
                validate_declared_output(root, entry.get("data"), f"figure {name} data")
            )
        elif status == "missing":
            if "html" in entry or "data" in entry:
                raise ReleaseError(f"Missing figure {name} unexpectedly declares files")
        else:
            raise ReleaseError(
                f"Unsupported interactive-report status for {name}: {status!r}"
            )
    inventory = (Path("MANIFEST.json"), *declared_paths)
    exact_file_inventory(root, inventory, "interactive reports")
    return inventory


def validate_gate_report(path: Path) -> None:
    report = load_json_object(path)
    name = path.name
    if name == "GATE_REPORT.json":
        if report.get("overall") != "PASS" or report.get("hard_failures") != 0:
            raise ReleaseError("Poster aggregate gate report is not a hard PASS")
        gates = report.get("gates")
        if not isinstance(gates, list) or not gates:
            raise ReleaseError("Poster aggregate gate report has no gates")
        for index, gate in enumerate(gates):
            if not isinstance(gate, dict):
                raise ReleaseError(f"Poster aggregate gate {index} is invalid")
            if gate.get("severity") == "hard" and gate.get("status") != "PASS":
                raise ReleaseError(f"Poster hard gate {index} did not pass")
        return
    status = report.get("status")
    if name == "style_check.json" and status != "PASS":
        raise ReleaseError("Poster style gate is not PASS")
    if name == "asset_check.json" and status not in {"PASS", "WARN"}:
        raise ReleaseError("Poster asset gate has an invalid status")
    checks = report.get("rules") if name == "style_check.json" else report.get("checks")
    if not isinstance(checks, list) or not checks:
        raise ReleaseError(f"Poster gate report {name} has no checks")
    for index, check in enumerate(checks):
        if not isinstance(check, dict):
            raise ReleaseError(f"Poster gate report {name} check {index} is invalid")
        if check.get("severity") == "hard" and check.get("status") not in {
            "PASS",
            "SKIPPED",
        }:
            raise ReleaseError(f"Poster hard check failed in {name}")


def reject_poster_placeholders(paths: Iterable[Path]) -> None:
    text_suffixes = {".css", ".html", ".js", ".json", ".md", ".txt"}
    for path in paths:
        if path.suffix.lower() not in text_suffixes:
            continue
        try:
            content = path.read_text(encoding="utf-8")
        except UnicodeDecodeError as error:
            raise ReleaseError(f"Poster text file is not UTF-8: {path}") from error
        match = PLACEHOLDER_PATTERN.search(content)
        if match is not None:
            raise ReleaseError(
                f"Unresolved poster placeholder in {path}: {match.group(0)}"
            )


def validate_poster_root(poster_root: Path) -> tuple[Path, ...]:
    root = require_real_directory(poster_root)
    manifest_path = require_real_file(root / "POSTER_MANIFEST.json")
    manifest = load_json_object(manifest_path)
    require_exact_keys(
        manifest, {"schema_version", "status", "files"}, "POSTER_MANIFEST.json"
    )
    if manifest["schema_version"] != "1.0.0" or manifest["status"] != "success":
        raise ReleaseError("Poster manifest is not a supported successful manifest")
    files = manifest["files"]
    if not isinstance(files, dict) or not files:
        raise ReleaseError("Poster manifest has no declared files")
    declared: dict[str, Path] = {}
    resolved_paths: list[Path] = []
    for raw_relative, declaration in sorted(files.items()):
        relative = safe_relative_path(raw_relative, "poster manifest file path")
        if not isinstance(declaration, dict):
            raise ReleaseError(f"Invalid poster declaration for {raw_relative}")
        require_exact_keys(
            declaration, {"sha256", "bytes", "role"}, f"poster {raw_relative}"
        )
        role = require_nonempty_string(
            declaration["role"], f"poster {raw_relative}.role"
        )
        expected_role = EXPECTED_POSTER_FILES.get(relative.as_posix())
        if expected_role is not None and role != expected_role:
            raise ReleaseError(f"Poster file {relative} has the wrong role")
        validate_declared_output(
            root, declaration, f"poster {raw_relative}", default_path=raw_relative
        )
        declared[relative.as_posix()] = relative
        resolved_paths.append(require_real_file(root / relative))
    missing = set(EXPECTED_POSTER_FILES) - set(declared)
    if missing:
        raise ReleaseError(
            f"Poster manifest is missing required files: {sorted(missing)}"
        )
    inventory = (Path("POSTER_MANIFEST.json"), *declared.values())
    exact_file_inventory(root, inventory, "poster bundle")
    reject_poster_placeholders([manifest_path, *resolved_paths])
    for gate_name in ("GATE_REPORT.json", "style_check.json", "asset_check.json"):
        validate_gate_report(root / gate_name)
    return inventory


def validate_release_readme(
    readme_path: Path, jobs_manifest: Mapping[str, Any]
) -> None:
    path = require_real_file(readme_path)
    try:
        content = path.read_text(encoding="utf-8")
    except UnicodeDecodeError as error:
        raise ReleaseError("Release README must be UTF-8") from error
    match = PLACEHOLDER_PATTERN.search(content)
    if match is not None:
        raise ReleaseError(f"Unresolved release README placeholder: {match.group(0)}")
    if len(content) < 1000 or len(re.findall(r"\b\w+\b", content)) < 120:
        raise ReleaseError("Release README is too short to be meaningful")
    headings = list(re.finditer(r"(?m)^(#{1,6})[ \t]+(.+?)[ \t]*$", content))
    h1 = [heading.group(2).strip() for heading in headings if heading.group(1) == "#"]
    if len(h1) != 1 or not all(
        token in h1[0].casefold() for token in ("chebyshev", "reproduc")
    ):
        raise ReleaseError(
            "Release README needs one descriptive Chebyshev reproduction H1"
        )
    h2 = {
        heading.group(2).strip(): heading
        for heading in headings
        if heading.group(1) == "##"
    }
    for required in REQUIRED_README_HEADINGS:
        heading = h2.get(required)
        if heading is None:
            raise ReleaseError(
                f"Release README is missing required heading: {required}"
            )
        section_start = heading.end()
        later_h2 = [
            candidate.start()
            for candidate in headings
            if candidate.group(1) in {"#", "##"} and candidate.start() > section_start
        ]
        section_end = min(later_h2, default=len(content))
        section = content[section_start:section_end]
        if len(re.findall(r"\b\w+\b", section)) < 8:
            raise ReleaseError(f"Release README section is not meaningful: {required}")

    required_links = {
        f"https://openreview.net/forum?id={EXPECTED_OPENREVIEW_ID}",
        f"https://arxiv.org/abs/{EXPECTED_PAPER_VERSION}",
        PUBLIC_BUCKET_URL,
        "jobs/HF_JOBS.json",
        "poster/poster.html",
        "RELEASE.json",
        *(f"interactive-reports/{key}.html" for key in EXPECTED_FIGURE_KEYS),
    }
    for attempt in jobs_manifest["attempts"]:
        if attempt["version"] == "v4":
            required_links.add(str(attempt["job_url"]))
    missing_links = sorted(link for link in required_links if link not in content)
    if missing_links:
        raise ReleaseError(f"Release README is missing required links: {missing_links}")
    command_semantics = (
        "scheduler_command",
        "reproduction_command",
        "inspected scheduler argv",
        "hash-verified rerun recipe",
    )
    missing_semantics = [
        marker for marker in command_semantics if marker not in content
    ]
    if missing_semantics:
        raise ReleaseError(
            "Release README does not distinguish scheduler evidence from rerun recipes; "
            f"missing={missing_semantics}"
        )


def extract_job_id(manifest: Mapping[str, Any]) -> str | None:
    hardware = manifest.get("hardware")
    environment = hardware.get("environment") if isinstance(hardware, dict) else None
    job_id = environment.get("JOB_ID") if isinstance(environment, dict) else None
    if job_id is None:
        return None
    if not isinstance(job_id, str) or HF_JOB_ID_PATTERN.fullmatch(job_id) is None:
        raise ReleaseError(f"Invalid Hugging Face Job id: {job_id!r}")
    return job_id


def checkpoint_records(batch: BatchData) -> list[Mapping[str, Any]]:
    output: list[Mapping[str, Any]] = []
    for record in batch.records:
        if record.get("record_type") != "artifact" or record.get("status") != "success":
            continue
        raw_path = record.get("artifact_path")
        if not isinstance(raw_path, str) or not raw_path.startswith(
            "artifacts/checkpoints/"
        ):
            continue
        relative = safe_relative_path(raw_path, "checkpoint artifact path")
        if len(relative.parts) != 3 or relative.parts[:2] != (
            "artifacts",
            "checkpoints",
        ):
            raise ReleaseError(f"Checkpoint must be a direct file: {raw_path}")
        if relative.suffix.lower() != ".json":
            raise ReleaseError(
                f"Only declared JSON checkpoints may be released: {raw_path}"
            )
        output.append(record)
    return sorted(output, key=lambda record: str(record["artifact_path"]))


def copy_raw_provenance(
    batches: Sequence[BatchData], destination: Path
) -> list[dict[str, Any]]:
    entries: list[dict[str, Any]] = []
    for batch in sorted(batches, key=lambda item: str(item.manifest["batch_id"])):
        manifest = batch.manifest
        batch_id = str(manifest["batch_id"])
        batch_destination = destination / batch_id
        copy_file(
            batch.directory / "manifest.json", batch_destination / "manifest.json"
        )
        input_hashes = manifest["input_hashes"]
        for name in sorted(input_hashes):
            relative = safe_relative_path(name, "input snapshot name")
            if len(relative.parts) != 1:
                raise ReleaseError(f"Input snapshot must be a direct file: {name}")
            copy_file(
                batch.directory / "inputs" / relative,
                batch_destination / "inputs" / relative,
            )

        checkpoints: list[dict[str, Any]] = []
        for record in checkpoint_records(batch):
            source_relative = Path(str(record["artifact_path"]))
            source = batch.directory / source_relative
            load_json_object(require_real_file(source))
            destination_relative = Path(source_relative.name)
            copy_file(
                source,
                batch_destination / "newly-trained-checkpoints" / destination_relative,
            )
            checkpoints.append(
                {
                    "path": (
                        Path("raw-provenance")
                        / batch_id
                        / "newly-trained-checkpoints"
                        / destination_relative
                    ).as_posix(),
                    "source_artifact_path": source_relative.as_posix(),
                    "sha256": require_sha256(
                        record.get("artifact_sha256"),
                        f"checkpoint {source_relative}.sha256",
                    ),
                    "bytes": record["artifact_bytes"],
                }
            )

        manifest_path = batch.directory / "manifest.json"
        records_path = batch.directory / "records.jsonl"
        job_id = extract_job_id(manifest)
        raw_url = f"{PUBLIC_BUCKET_URL}/resolve/raw/{batch_id}"
        entries.append(
            {
                "batch_id": batch_id,
                "job": None
                if job_id is None
                else {
                    "id": job_id,
                    "url": f"https://huggingface.co/jobs/{HF_NAMESPACE}/{job_id}",
                },
                "manifest": {
                    "url": f"{raw_url}/manifest.json",
                    "sha256": batch.manifest_sha256,
                    "bytes": manifest_path.stat().st_size,
                },
                "records": {
                    "url": f"{raw_url}/records.jsonl",
                    "sha256": batch.records_sha256,
                    "bytes": records_path.stat().st_size,
                },
                "runner_sha256": manifest["runner_sha256"],
                "input_hashes": dict(sorted(input_hashes.items())),
                "record_counts": manifest["record_counts"],
                "checkpoints": checkpoints,
            }
        )
    if not entries:
        raise ReleaseError("At least one validated raw batch is required")
    return entries


def write_release_metadata(staging: Path, batches: list[dict[str, Any]]) -> None:
    metadata = {
        "schema_version": "1.1.0",
        "paper": {
            "openreview_id": EXPECTED_OPENREVIEW_ID,
            "arxiv_version": EXPECTED_PAPER_VERSION,
        },
        "evidence_bucket": {
            "url": PUBLIC_BUCKET_URL,
            "raw_resolve_url": f"{PUBLIC_BUCKET_URL}/resolve/raw",
        },
        "raw_records_policy": (
            "Raw records are hash-anchored by the included manifests and remain in "
            "the public Hugging Face evidence Bucket; they are not duplicated here."
        ),
        "batches": sorted(batches, key=lambda batch: str(batch["batch_id"])),
    }
    (staging / "RELEASE.json").write_text(
        json.dumps(metadata, indent=2, sort_keys=True) + "\n", encoding="utf-8"
    )


def write_hash_manifest(staging: Path) -> None:
    entries: list[str] = []
    paths = sorted(
        staging.rglob("*"),
        key=lambda path: path.relative_to(staging).as_posix(),
    )
    for path in paths:
        if path.is_symlink():
            raise ReleaseError(f"Symlink found in staged release: {path}")
        if path.is_file() and path != staging / "MANIFEST.sha256":
            entries.append(
                f"{sha256_file(path)}  {path.relative_to(staging).as_posix()}"
            )
    if not entries:
        raise ReleaseError("Release staging tree is empty")
    (staging / "MANIFEST.sha256").write_text(
        "\n".join(entries) + "\n", encoding="utf-8"
    )


def reject_secret_content(staging: Path) -> None:
    for path in sorted(
        staging.rglob("*"),
        key=lambda candidate: candidate.relative_to(staging).as_posix(),
    ):
        if not path.is_file():
            continue
        payload = path.read_bytes()
        for pattern, label in SECRET_CONTENT_PATTERNS:
            if pattern.search(payload) is not None:
                relative = path.relative_to(staging)
                raise ReleaseError(
                    f"Possible {label} found in release file: {relative}"
                )


def publish_directory(staging: Path, destination: Path, replace: bool) -> None:
    if destination.is_symlink():
        raise ReleaseError(f"Refusing to publish through a symlink: {destination}")
    if destination.exists() and not destination.is_dir():
        raise ReleaseError(f"Output path exists and is not a directory: {destination}")
    if destination.exists() and not replace:
        raise ReleaseError(
            f"Output directory already exists: {destination}; pass --replace"
        )
    destination.parent.mkdir(parents=True, exist_ok=True)
    if not destination.exists():
        os.replace(staging, destination)
        return
    backup = destination.parent / f".{destination.name}.old-{os.getpid()}"
    if backup.exists():
        raise ReleaseError(f"Refusing to overwrite stale backup directory: {backup}")
    os.replace(destination, backup)
    try:
        os.replace(staging, destination)
    except BaseException:
        os.replace(backup, destination)
        raise
    shutil.rmtree(backup)


def build_release(args: argparse.Namespace) -> Path:
    project_root = require_real_directory(args.project_root)
    if args.output_root.is_symlink():
        raise ReleaseError(f"Release output cannot be a symlink: {args.output_root}")
    output_root = args.output_root.resolve()

    project_directories = [
        project_root / "configs",
        project_root / "scripts",
        project_root / "experiments",
        project_root / "tests",
    ]
    external_directories = [
        args.jobs_root,
        args.tables_root,
        args.analysis_root,
        args.reports_root,
        args.poster_root,
        *args.raw_root,
    ]
    source_paths = [
        require_real_file(args.release_readme),
        *(require_real_directory(path) for path in project_directories),
        *(require_real_directory(path) for path in external_directories),
    ]
    validate_source_destination_disjoint(output_root, source_paths)

    runner_path = project_root / "scripts" / "run_reproduction.py"
    batches = load_validated_batches(args.raw_root, runner_path)
    jobs_manifest, job_paths = validate_jobs_root(args.jobs_root, batches, runner_path)
    tables_manifest, table_paths = validate_tables_root(
        args.tables_root,
        batches,
        builder_script=project_root / "scripts" / "build_tables.py",
        raw_roots=args.raw_root,
    )
    analysis_paths = validate_analysis_root(
        args.analysis_root,
        args.tables_root,
        tables_manifest,
        builder_script=project_root / "scripts" / "analyze_claims.py",
    )
    report_paths = validate_reports_root(
        args.reports_root,
        args.tables_root,
        tables_manifest,
        builder_script=project_root / "scripts" / "make_figures.py",
    )
    poster_paths = validate_poster_root(args.poster_root)
    validate_release_readme(args.release_readme, jobs_manifest)

    output_root.parent.mkdir(parents=True, exist_ok=True)
    staging = Path(
        tempfile.mkdtemp(prefix=f".{output_root.name}.tmp-", dir=output_root.parent)
    )
    try:
        copy_file(args.release_readme, staging / "README.md")
        copy_file(project_root / "README.md", staging / "docs" / "WORKFLOW.md")
        for filename in (
            "pyproject.toml",
            "uv.lock",
            ".python-version",
            "upstream.lock.json",
        ):
            copy_file(project_root / filename, staging / filename)
        copy_tree(
            project_root / "configs", staging / "configs", allowed_suffixes={".json"}
        )
        copy_tree(
            project_root / "scripts",
            staging / "scripts",
            allowed_suffixes={".py", ".sh"},
        )
        copy_tree(
            project_root / "experiments",
            staging / "experiments",
            allowed_suffixes={".md"},
        )
        copy_tree(project_root / "tests", staging / "tests", allowed_suffixes={".py"})
        copy_verified_files(args.jobs_root, staging / "jobs", job_paths)
        copy_verified_files(args.tables_root, staging / "tables", table_paths)
        copy_verified_files(args.analysis_root, staging / "analysis", analysis_paths)
        copy_verified_files(
            args.reports_root, staging / "interactive-reports", report_paths
        )
        copy_verified_files(args.poster_root, staging / "poster", poster_paths)
        batch_entries = copy_raw_provenance(
            batches,
            staging / "raw-provenance",
        )
        write_release_metadata(staging, batch_entries)
        reject_secret_content(staging)
        write_hash_manifest(staging)
        publish_directory(staging, output_root, args.replace)
    except BaseException:
        shutil.rmtree(staging, ignore_errors=True)
        raise
    return output_root


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--project-root", type=Path, required=True)
    parser.add_argument("--release-readme", type=Path, required=True)
    parser.add_argument("--raw-root", type=Path, action="append", required=True)
    parser.add_argument("--jobs-root", type=Path, required=True)
    parser.add_argument("--tables-root", type=Path, required=True)
    parser.add_argument("--analysis-root", type=Path, required=True)
    parser.add_argument("--reports-root", type=Path, required=True)
    parser.add_argument("--poster-root", type=Path, required=True)
    parser.add_argument("--output-root", type=Path, required=True)
    parser.add_argument("--replace", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    try:
        output = build_release(args)
    except (OSError, ReleaseError, ValueError) as error:
        raise SystemExit(f"build_release: ERROR: {error}") from error
    print(output)


if __name__ == "__main__":
    main()