speccoder_runtime/

held_out.rs

//! Held-out acceptance tests: written by a second author call
//! after the visible ones, kept in the state directory — never in the
//! worktree, never in an implementer's input — red-checked on the
//! checkpoint, and run over the final tree after an attempt that passed
//! visibly. Only the scenario IDs of a failure reach a retry.

use std::collections::BTreeSet;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};
use speccoder_core::verify::{CheckResult, RunnerSummary};

use crate::git::Git;
use crate::integrity::{JudgeSnapshot, sha256_hex};
use crate::tools::policy::Policy;
use crate::{sandbox, worktree};

/// Held-out files per task, composition tests included.
pub const LIMIT: usize = 4;

/// One kept held-out test file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct HeldOutFile {
    /// Workspace-relative path it is written to for a run.
    pub path: String,
    /// SHA-256 of its content.
    pub sha256: String,
    /// The scenarios it covers.
    pub scenarios: Vec<String>,
    /// The command that runs only it.
    pub argv: Vec<String>,
    /// It exercises several scenarios together.
    pub composition: bool,
}

/// A file the author wrote that was not kept, and why.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Discarded {
    /// Its path as given.
    pub path: String,
    /// `unknown_scenario`, `not_covered_by_visible`, `path`, `command`,
    /// `not_red`, `collision` or `limit`.
    pub reason: String,
}

/// What judged a task, stored beside the files' contents.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Manifest {
    /// Format version.
    pub version: u32,
    /// The feature (or change).
    pub feature: String,
    /// The task.
    pub task: String,
    /// The author run.
    pub author_run: String,
    /// The tree the red runs used.
    pub checkpoint: String,
    /// Scenarios this task's acceptance tests cover.
    pub visible_scenarios: Vec<String>,
    /// Kept files.
    pub files: Vec<HeldOutFile>,
    /// Files not kept.
    pub discarded: Vec<Discarded>,
}

impl Manifest {
    /// SHA-256 of the canonical JSON: what the ticking commit names.
    #[must_use]
    pub fn sha256(&self) -> String {
        sha256_hex(&serde_json::to_vec(self).unwrap_or_default())
    }
}

/// Where a task's held-out set lives: `<project state>/held-out/<feature>/<task>`.
#[must_use]
pub fn dir(project_state: &Path, feature: &str, task: &str) -> PathBuf {
    project_state.join("held-out").join(feature).join(task)
}

/// Stores the manifest and the kept files' contents; returns the
/// manifest's hash. A previous set for the task is replaced.
pub fn store(
    dir: &Path,
    manifest: &Manifest,
    contents: &[(String, String)],
) -> Result<String, String> {
    let _ = std::fs::remove_dir_all(dir);
    for (path, content) in contents {
        let file = dir.join("files").join(path);
        if let Some(parent) = file.parent() {
            std::fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?;
        }
        std::fs::write(&file, content).map_err(|e| format!("{}: {e}", file.display()))?;
    }
    std::fs::create_dir_all(dir).map_err(|e| format!("{}: {e}", dir.display()))?;
    let text = serde_json::to_string_pretty(manifest).map_err(|e| e.to_string())?;
    std::fs::write(dir.join("manifest.json"), text).map_err(|e| e.to_string())?;
    Ok(manifest.sha256())
}

/// Where a sealed set lives: `<project state>/held-out/<unit>/req-<key>/`
/// (run-time task sets stay at `<unit>/<task>/`).
#[must_use]
pub fn sealed_dir(project_state: &Path, unit: &str, key: &str) -> PathBuf {
    project_state
        .join("held-out")
        .join(unit)
        .join(format!("req-{}", key.replace([':', '/'], "-")))
}

/// Seals a held-out set keyed by `(unit, requirement)` — the entry point
/// for sets decided before a run (a bug's reproduction variants, a
/// review's oracle): the one store protocol, each manifest entry citing
/// its statements or scenarios.
pub fn seal(
    project_state: &Path,
    unit: &str,
    key: &str,
    manifest: &Manifest,
    contents: &[(String, String)],
) -> Result<speccoder_core::acceptance::SealedRef, String> {
    let sha = store(&sealed_dir(project_state, unit, key), manifest, contents)?;
    Ok(speccoder_core::acceptance::SealedRef {
        key: key.to_owned(),
        manifest_sha256: sha,
        count: manifest.files.len(),
    })
}

/// A sealed set, checked against its reference.
pub fn open_sealed(
    project_state: &Path,
    unit: &str,
    sealed: &speccoder_core::acceptance::SealedRef,
) -> Result<(Manifest, Vec<(String, String)>), Tampered> {
    load_verified(
        &sealed_dir(project_state, unit, &sealed.key),
        &sealed.manifest_sha256,
    )
}

/// A stored set that no longer matches what was recorded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Tampered(pub String);

/// The stored set, checked: the manifest must hash to `expected` and every
/// file to its recorded hash.
pub fn load_verified(
    dir: &Path,
    expected: &str,
) -> Result<(Manifest, Vec<(String, String)>), Tampered> {
    let text = std::fs::read_to_string(dir.join("manifest.json"))
        .map_err(|e| Tampered(format!("the held-out manifest is unreadable: {e}")))?;
    let manifest: Manifest = serde_json::from_str(&text)
        .map_err(|e| Tampered(format!("the held-out manifest is not valid: {e}")))?;
    if manifest.sha256() != expected {
        return Err(Tampered(
            "the held-out manifest changed since it was written".to_owned(),
        ));
    }
    let mut contents = Vec::new();
    for f in &manifest.files {
        let content = std::fs::read_to_string(dir.join("files").join(&f.path))
            .map_err(|_| Tampered(format!("held-out file {} is missing", f.path)))?;
        if sha256_hex(content.as_bytes()) != f.sha256 {
            return Err(Tampered(format!("held-out file {} changed", f.path)));
        }
        contents.push((f.path.clone(), content));
    }
    Ok((manifest, contents))
}

/// One held-out file's run.
#[derive(Debug, Clone)]
pub struct Ran {
    /// Its path.
    pub path: String,
    /// The run, or `None` when its path already existed (not overwritten).
    pub result: Option<(CheckResult, Option<RunnerSummary>)>,
    /// The same command on the tree without any held-out file, when asked
    /// for ([`overlay_red`]): what the command fails anyway is not this
    /// file's red.
    pub without: Option<(CheckResult, Option<RunnerSummary>)>,
}

/// The marker a worktree carries while held-out files are overlaid on it:
/// in its git admin directory (outside the tree), naming each overlaid
/// path by its SHA-256 only — so a view of the worktree can hide them
/// without the marker telling anyone what they are.
const OVERLAY_MARKER: &str = "speccoder-held-out-overlay.json";

fn overlay_marker(wt_root: &Path) -> Option<PathBuf> {
    crate::git::Git::at(wt_root)
        .line(&["rev-parse", "--absolute-git-dir"])
        .ok()
        .filter(|d| !d.is_empty())
        .map(|d| PathBuf::from(d).join(OVERLAY_MARKER))
}

/// The digests of the worktree-relative paths overlaid on `wt_root` now:
/// `Some(empty)` when nothing is; `None` when a marker exists that cannot
/// be read (then nothing untracked may be shown).
#[must_use]
pub fn overlaid(wt_root: &Path) -> Option<Vec<String>> {
    let Some(marker) = overlay_marker(wt_root) else {
        return Some(Vec::new());
    };
    match std::fs::read_to_string(&marker) {
        Ok(t) => serde_json::from_str(&t).ok(),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Some(Vec::new()),
        Err(_) => None,
    }
}

/// The SHA-256 a worktree-relative path is named by in the marker.
#[must_use]
pub fn overlay_key(rel: &str) -> String {
    sha256_hex(rel.as_bytes())
}

/// Removes the marker when the overlay ends, however it ends.
struct OverlayMarker(Option<PathBuf>);

impl Drop for OverlayMarker {
    fn drop(&mut self) {
        if let Some(m) = &self.0 {
            let _ = std::fs::remove_file(m);
        }
    }
}

/// Writes each held-out file over the worktree, runs its command, and puts
/// the tree back exactly as it was: no file of the set, nothing a test wrote,
/// no changed judge input survives — a later attempt can read none of it.
/// While it runs, the worktree's marker hides the files from its views.
pub fn overlay_run(
    wt_root: &Path,
    project: &Path,
    tmp: &Path,
    files: &[(HeldOutFile, String)],
    runner: &sandbox::Runner,
    policy: &Policy,
) -> Result<Vec<Ran>, String> {
    overlay(wt_root, project, tmp, files, runner, policy, false)
}

/// One command's run: its result and the runner's summary, if read.
type Outcome = (CheckResult, Option<RunnerSummary>);

/// [`overlay_run`] for a red check: each distinct command also runs once on
/// the tree without any held-out file, so a file is red only by the failing
/// tests it adds ([`speccoder_core::verify::classify_red_added`]).
pub fn overlay_red(
    wt_root: &Path,
    project: &Path,
    tmp: &Path,
    files: &[(HeldOutFile, String)],
    runner: &sandbox::Runner,
    policy: &Policy,
) -> Result<Vec<Ran>, String> {
    overlay(wt_root, project, tmp, files, runner, policy, true)
}

/// The red class of one held-out run: by what its file adds when the run
/// without it is known, else by the run alone.
#[must_use]
pub fn red_class(ran: &Ran) -> speccoder_core::verify::RedClass {
    use speccoder_core::verify::{RedClass, classify_red, classify_red_added};
    match (&ran.result, &ran.without) {
        (None, _) => RedClass::Unclassified,
        (Some((r, s)), Some((o, os))) => classify_red_added((r, s.as_ref()), (o, os.as_ref())),
        (Some((r, s)), None) => classify_red(r, s.as_ref()),
    }
}

fn overlay(
    wt_root: &Path,
    project: &Path,
    tmp: &Path,
    files: &[(HeldOutFile, String)],
    runner: &sandbox::Runner,
    policy: &Policy,
    baseline: bool,
) -> Result<Vec<Ran>, String> {
    let before = worktree::checkpoint(wt_root, tmp).map_err(|e| e.0)?;
    let judged = JudgeSnapshot::take(wt_root, policy);
    let prefix = {
        let canonical = |p: &Path| std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf());
        canonical(project)
            .strip_prefix(canonical(wt_root))
            .map(|r| r.to_string_lossy().replace('\\', "/"))
            .unwrap_or_default()
    };
    // Each file and each directory above it (a new directory is listed
    // untracked as a whole).
    let mut keys: Vec<String> = Vec::new();
    for (f, _) in files {
        let rel = if prefix.is_empty() {
            f.path.clone()
        } else {
            format!("{prefix}/{}", f.path)
        };
        let mut at = rel.as_str();
        loop {
            let key = overlay_key(at);
            if !keys.contains(&key) {
                keys.push(key);
            }
            match at.rfind('/') {
                Some(i) => at = &at[..i],
                None => break,
            }
        }
    }
    let marker = OverlayMarker(overlay_marker(wt_root));
    if let Some(m) = &marker.0 {
        std::fs::write(m, serde_json::to_string(&keys).unwrap_or_default())
            .map_err(|e| format!("the held-out overlay marker: {e}"))?;
    }
    // Each distinct command once on the tree as it is, before any file.
    let mut without: Vec<(Vec<String>, Outcome)> = Vec::new();
    if baseline {
        for (f, _) in files {
            if !without.iter().any(|(argv, _)| *argv == f.argv) {
                let ran = crate::pipeline::acceptance_run(project, &f.argv, runner);
                without.push((f.argv.clone(), ran));
            }
        }
    }
    let without_of = |argv: &[String]| {
        without
            .iter()
            .find(|(a, _)| a.as_slice() == argv)
            .map(|(_, r)| r.clone())
    };
    let mut out = Vec::new();
    for (f, content) in files {
        let full = project.join(&f.path);
        if full.exists() {
            out.push(Ran {
                path: f.path.clone(),
                result: None,
                without: None,
            });
            continue;
        }
        if let Some(parent) = full.parent() {
            let _ = std::fs::create_dir_all(parent);
        }
        std::fs::write(&full, content).map_err(|e| format!("{}: {e}", f.path))?;
        let ran = crate::pipeline::acceptance_run(project, &f.argv, runner);
        let _ = std::fs::remove_file(&full);
        out.push(Ran {
            path: f.path.clone(),
            result: Some(ran),
            without: without_of(&f.argv),
        });
    }
    worktree::restore(wt_root, tmp, &before).map_err(|e| e.0)?;
    // What a test wrote to its private scratch would outlive the run.
    if let Some(scratch) = runner.scratch() {
        let _ = std::fs::remove_dir_all(&scratch);
    }
    let after = worktree::checkpoint(wt_root, tmp).map_err(|e| e.0)?;
    if after != before {
        return Err("the held-out run left changes in the worktree".to_owned());
    }
    let drift = judged.drift(
        &JudgeSnapshot::take(wt_root, policy),
        policy,
        &BTreeSet::new(),
    );
    if let Some(d) = drift.first() {
        return Err(format!("the held-out run changed judge input {}", d.path));
    }
    Ok(out)
}

/// Literals a copied test would carry: quoted strings of 6+ characters and
/// numbers with 4+ significant digits.
#[must_use]
pub fn literals(text: &str) -> BTreeSet<String> {
    let mut out = BTreeSet::new();
    for quote in ['"', '\''] {
        let mut parts = text.split(quote);
        parts.next();
        while let (Some(inside), Some(_)) = (parts.next(), parts.next().or(Some(""))) {
            if inside.chars().count() >= 6 && !inside.contains('\n') {
                out.insert(inside.to_owned());
            }
        }
    }
    let mut number = String::new();
    for c in text.chars().chain(std::iter::once(' ')) {
        if c.is_ascii_digit() || (c == '.' && !number.is_empty()) {
            number.push(c);
        } else {
            let n = number.trim_end_matches('.');
            let significant = n
                .trim_start_matches(['0', '.'])
                .chars()
                .filter(char::is_ascii_digit)
                .count();
            if significant >= 4 {
                out.insert(n.to_owned());
            }
            number.clear();
        }
    }
    out
}

/// Held-out literals in the attempt's added lines that it could only have
/// copied: not in the spec, the visible tests or the tree it started from
///. For a native attempt this never fires; for an external
/// agent, which can read the state directory, it is the mechanical check.
#[must_use]
pub fn leaked(
    held_out: &[(HeldOutFile, String)],
    known: &str,
    wt_root: &Path,
    start_tree: &worktree::Checkpoint,
    patch: &str,
) -> Vec<String> {
    let added: String = patch
        .lines()
        .filter(|l| l.starts_with('+') && !l.starts_with("+++"))
        .collect::<Vec<_>>()
        .join("\n");
    let git = Git::at(wt_root);
    held_out
        .iter()
        .flat_map(|(_, content)| literals(content))
        .collect::<BTreeSet<_>>()
        .into_iter()
        .filter(|lit| added.contains(lit.as_str()) && !known.contains(lit.as_str()))
        .filter(|lit| {
            !git.succeeds(&["grep", "-q", "-F", "-e", lit, &start_tree.0])
                .unwrap_or(true)
        })
        .collect()
}

/// Where a unit's published held-out sets live.
pub const REF_PREFIX: &str = "refs/speccoder/held-out";

/// The held-out sets a publication carries: exactly those whose manifest
/// digest a task closed on the pushed head names in its evidence.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Selection {
    /// `(store key, its directory)` of every set carried.
    pub sets: Vec<(String, PathBuf)>,
    /// The closed tasks whose sets are carried, in order.
    pub tasks: Vec<String>,
    /// Stored sets no closed task names (open tasks'): they stay local.
    pub withheld: usize,
    /// Named sets that no longer match their digest: left out, by key.
    pub tampered: Vec<String>,
}

/// The digests a task commit's evidence names: the signed `held_out`
/// phase, else the commit's `Held-Out:` trailer.
#[must_use]
pub fn named_digests(repo: &Path, commit: &str) -> Vec<String> {
    let mut out: Vec<String> = crate::evidence::statements(repo, commit)
        .iter()
        .filter(|s| s["predicate"]["configuration"][0]["name"] == "speccoder:phase/held_out")
        .filter_map(|s| {
            s["predicate"]["configuration"][0]["digest"]["sha256"]
                .as_str()
                .map(str::to_owned)
        })
        .collect();
    let trailer = Git::at(repo)
        .line(&[
            "log",
            "-1",
            "--format=%(trailers:key=Held-Out,valueonly)",
            commit,
        ])
        .unwrap_or_default();
    out.extend(
        trailer
            .split_whitespace()
            .filter_map(|w| w.strip_prefix("manifest=sha256:"))
            .map(str::to_owned),
    );
    out.sort();
    out.dedup();
    out
}

/// Selects, from every set stored for `unit` (whatever its key: a task's
/// today, a sealed set's once the store holds them — one protocol), those
/// whose manifest digest a closed task names. `closed` is `(task, digests
/// its evidence names)`. Each selected set is checked against its digest
/// first; a tampered one is never published.
#[must_use]
pub fn select_closed(
    project_state: &Path,
    unit: &str,
    closed: &[(String, Vec<String>)],
) -> Selection {
    let base = project_state.join("held-out").join(unit);
    let mut stored: Vec<(String, PathBuf)> = std::fs::read_dir(&base)
        .into_iter()
        .flatten()
        .flatten()
        .filter(|e| e.path().join("manifest.json").is_file())
        .map(|e| (e.file_name().to_string_lossy().into_owned(), e.path()))
        .collect();
    stored.sort();
    let mut out = Selection::default();
    for (key, dir) in stored {
        let digest = std::fs::read_to_string(dir.join("manifest.json"))
            .ok()
            .and_then(|t| serde_json::from_str::<Manifest>(&t).ok())
            .map(|m| m.sha256());
        let named_by = digest.as_ref().and_then(|d| {
            closed
                .iter()
                .find(|(_, digests)| digests.contains(d))
                .map(|(task, _)| task.clone())
        });
        match (named_by, digest) {
            (Some(task), Some(d)) => {
                if load_verified(&dir, &d).is_ok() {
                    if !out.tasks.contains(&task) {
                        out.tasks.push(task);
                    }
                    out.sets.push((key, dir));
                } else {
                    out.tampered.push(key);
                }
            }
            _ => out.withheld += 1,
        }
    }
    out
}

/// The private repository publications are built in: a bare repository
/// in the project's state directory that borrows the project's objects
/// (`objects/info/alternates`), so the tip a publication is parented on
/// resolves there while the held-out tests themselves never enter the
/// project's repository. Every attempt can read that repository's refs
/// and objects (`git show`, `git fsck --unreachable`, a script a check
/// runs); none can read the state directory.
///
/// # Errors
///
/// The repository cannot be created, or the project's objects not found.
pub fn publication_store(project_state: &Path, repo: &Path) -> Result<PathBuf, String> {
    let dir = project_state.join("held-out.git");
    if !dir.join("HEAD").is_file() {
        std::fs::create_dir_all(&dir).map_err(|e| format!("{}: {e}", dir.display()))?;
        Git::at(&dir)
            .run(&["init", "-q", "--bare"])
            .map_err(|e| e.0)?;
    }
    let common = Git::at(repo)
        .line(&["rev-parse", "--path-format=absolute", "--git-common-dir"])
        .map_err(|e| e.0)?;
    let info = dir.join("objects/info");
    std::fs::create_dir_all(&info).map_err(|e| format!("{}: {e}", info.display()))?;
    std::fs::write(
        info.join("alternates"),
        format!("{}\n", Path::new(&common).join("objects").display()),
    )
    .map_err(|e| format!("{}: {e}", info.display()))?;
    // A publication an earlier version left in the project moves here:
    // later pushes still fast-forward it, and no attempt finds it by name.
    let project = Git::at(repo);
    let legacy = project
        .line(&[
            "for-each-ref",
            "--format=%(refname) %(objectname)",
            REF_PREFIX,
        ])
        .map_err(|e| e.0)?;
    let private = Git::at(&dir);
    for line in legacy.lines() {
        let Some((name, commit)) = line.split_once(' ') else {
            continue;
        };
        if !private
            .succeeds(&["rev-parse", "--verify", "-q", name])
            .unwrap_or(false)
        {
            private
                .run(&["update-ref", name, commit])
                .map_err(|e| e.0)?;
        }
        project.run(&["update-ref", "-d", name]).map_err(|e| e.0)?;
    }
    Ok(dir)
}

/// Pushes `commit` (built in `store`) to `remote`'s
/// `refs/speccoder/held-out/<unit>` from `repo`, reading the store's
/// objects as alternates: nothing is written to `repo`, no local ref
/// either.
///
/// # Errors
///
/// The push failed (not a fast-forward, no access).
pub fn push(
    repo: &Path,
    store: &Path,
    remote: &str,
    unit: &str,
    commit: &str,
) -> Result<(), String> {
    let objects = store.join("objects");
    Git::at(repo)
        .run_with_env(
            &[
                "push",
                "--quiet",
                remote,
                &format!("{commit}:{REF_PREFIX}/{unit}"),
            ],
            &[("GIT_ALTERNATE_OBJECT_DIRECTORIES", objects.as_os_str())],
        )
        .map(|_| ())
        .map_err(|e| e.0)
}

/// Publishes `selection` as one commit under
/// `refs/speccoder/held-out/<unit>` of the private `store`
/// ([`publication_store`]):
/// `<key>/manifest.json` and `<key>/files/…` of every set, parented on
/// `tip` (the pushed branch) and on the ref's previous commit, so the ref
/// only grows and every push of it is a fast-forward. `Ok(None)` when
/// nothing is selected.
pub fn publish_closed(
    store: &Path,
    unit: &str,
    tip: &str,
    selection: &Selection,
    tmp: &Path,
) -> Result<Option<String>, String> {
    let mut files: Vec<(String, PathBuf)> = Vec::new();
    for (key, dir) in &selection.sets {
        let mut stack = vec![dir.clone()];
        while let Some(d) = stack.pop() {
            let Ok(entries) = std::fs::read_dir(&d) else {
                continue;
            };
            for e in entries.flatten() {
                let p = e.path();
                if p.is_dir() {
                    stack.push(p);
                } else if let Ok(rel) = p.strip_prefix(dir) {
                    let rel = rel.to_string_lossy().replace('\\', "/");
                    files.push((format!("{key}/{rel}"), p.clone()));
                }
            }
        }
    }
    if files.is_empty() {
        return Ok(None);
    }
    files.sort();
    let git = Git::at(store);
    std::fs::create_dir_all(tmp).map_err(|e| e.to_string())?;
    let index = tmp.join(format!("held-out-index-{}", std::process::id()));
    let _ = std::fs::remove_file(&index);
    for (rel, path) in &files {
        let blob = git
            .line(&["hash-object", "-w", "--", &path.to_string_lossy()])
            .map_err(|e| e.0)?;
        git.run_with_index(
            &index,
            &[
                "update-index",
                "--add",
                "--cacheinfo",
                &format!("100644,{blob},{rel}"),
            ],
            None,
        )
        .map_err(|e| e.0)?;
    }
    let tree = git
        .run_with_index(&index, &["write-tree"], None)
        .map_err(|e| e.0)?;
    let _ = std::fs::remove_file(&index);
    let tree = String::from_utf8_lossy(&tree).trim().to_owned();
    let reference = format!("{REF_PREFIX}/{unit}");
    let previous = git
        .line(&[
            "rev-parse",
            "--verify",
            "-q",
            &format!("{reference}^{{commit}}"),
        ])
        .ok()
        .filter(|c| !c.is_empty());
    // Nothing new since the last publication of this tip: keep it.
    if let Some(prev) = &previous
        && git
            .line(&["rev-parse", &format!("{prev}^{{tree}}")])
            .ok()
            .as_deref()
            == Some(&tree)
        && git
            .succeeds(&["merge-base", "--is-ancestor", tip, prev])
            .unwrap_or(false)
    {
        return Ok(Some(prev.clone()));
    }
    let message = format!(
        "speccoder: held-out tests of {unit}\n\nThe tests that judged the tasks closed on {tip}: {}.\nEach <key>/manifest.json hashes to the digest its task's evidence names.\n\nSpec-Feature: {unit}\n",
        selection.tasks.join(", ")
    );
    let mut args = crate::attempts::IDENTITY.to_vec();
    args.extend(["commit-tree", &tree, "-p", tip]);
    if let Some(prev) = &previous {
        args.extend(["-p", prev]);
    }
    args.extend(["-m", &message]);
    let commit = git.line(&args).map_err(|e| e.0)?;
    git.run(&["update-ref", &reference, &commit])
        .map_err(|e| e.0)?;
    Ok(Some(commit))
}

/// Publishes a finished feature's held-out sets in the private store
/// (every task is closed then): [`publish_closed`] over the tasks the
/// branch tip closes. Never pushed here; `speccoder pr` pushes it.
/// `Ok(None)` when no closed task names a stored set.
pub fn publish(
    repo: &Path,
    project_state: &Path,
    feature: &str,
    tmp: &Path,
) -> Result<Option<String>, String> {
    let branch = format!("speccoder/{feature}");
    let tip = Git::at(repo)
        .line(&["rev-parse", "--verify", &format!("{branch}^{{commit}}")])
        .map_err(|e| e.0)?;
    let closed = closed_on(repo, &tip, feature);
    let selection = select_closed(project_state, feature, &closed);
    if selection.sets.is_empty() {
        return Ok(None);
    }
    publish_closed(
        &publication_store(project_state, repo)?,
        feature,
        &tip,
        &selection,
        tmp,
    )
}

/// The tasks of `unit` closed on `head` (ticked, with the commit carrying
/// their verdict — the verifier's discovery), each with the held-out
/// digests its evidence names.
#[must_use]
pub fn closed_on(repo: &Path, head: &str, unit: &str) -> Vec<(String, Vec<String>)> {
    crate::attest::branch::closed(repo, head, unit)
        .into_iter()
        .map(|(task, commit)| {
            let digests = named_digests(repo, &commit);
            (task, digests)
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn literals_are_long_strings_and_precise_numbers() {
        let l = literals(
            "assert_eq!(slug(\"Hello, World\"), \"hello-world\"); x(3.14159); y(42); z('ab')",
        );
        assert!(l.contains("Hello, World") && l.contains("hello-world"));
        assert!(l.contains("3.14159"));
        assert!(!l.contains("42") && !l.contains("ab"));
    }

    #[test]
    fn a_changed_file_or_manifest_is_tampering() {
        let d = tempfile::tempdir().unwrap();
        let content = "fn t() {}\n".to_owned();
        let m = Manifest {
            version: 1,
            feature: "f".to_owned(),
            task: "T1".to_owned(),
            author_run: "r".to_owned(),
            checkpoint: "c".to_owned(),
            visible_scenarios: vec!["US1-1".to_owned()],
            files: vec![HeldOutFile {
                path: "tests/h.rs".to_owned(),
                sha256: sha256_hex(content.as_bytes()),
                scenarios: vec!["US1-1".to_owned()],
                argv: vec!["true".to_owned()],
                composition: false,
            }],
            discarded: Vec::new(),
        };
        let sha = store(d.path(), &m, &[("tests/h.rs".to_owned(), content)]).unwrap();
        assert_eq!(load_verified(d.path(), &sha).unwrap().1.len(), 1);
        assert!(load_verified(d.path(), "other").is_err());
        std::fs::write(d.path().join("files/tests/h.rs"), "fn t() { changed }").unwrap();
        assert!(
            load_verified(d.path(), &sha)
                .unwrap_err()
                .0
                .contains("changed")
        );
        std::fs::remove_file(d.path().join("files/tests/h.rs")).unwrap();
        assert!(
            load_verified(d.path(), &sha)
                .unwrap_err()
                .0
                .contains("missing")
        );
    }
}