//! The roll API's client side, shared by `concept-seed` (the roll and the
//! agent-run choice ping) and `serve-question` (the picker's own ping).
//!
//! Three pieces live here:
//! - the request plumbing: API base, timeout, opt-outs, and the
//!   `X-Impeccable-Client` header every `/api/roll` and `/api/chosen` request
//!   carries;
//! - the seed reference and the seed ledger. The reference,
//!   `seed:<16 hex of sha256("impeccable-seed:" + key)>`, is what committed
//!   files (the surface brief's FORM line) record instead of the key. The
//!   ledger, `.impeccable/questions/seeds/<those 16 hex>.json`, is the local,
//!   self-ignored record that resolves a reference back to its key on this
//!   machine (`{"key"}`, written for every roll), plus, only while telemetry
//!   is on, one entry per API-dealt round (`poolRevision`, the dealt catalog
//!   ids) and the marker that a round's choice was already sent. Unlike
//!   `roll.json`, which a decision page removes when it takes the roll, the
//!   ledger outlives the page, so the ping the agent sends after the round
//!   still finds its round;
//! - the choice ping body and its send.

use crate::jsp;
use crate::util::{json_compact, safe_read, Env};
use serde_json::{json, Map, Value};
use std::time::Duration;

/// The kinds a choice ping may send. `reroll` means the hand was rejected:
/// the user asked for another hand instead of choosing.
pub const KINDS: [&str; 6] = ["assigned", "pick", "challenger", "canon", "reroll", "grounded"];

/// The kinds a decision-page option card declares. `grounded` is one of the
/// agent's grounded directions that is neither the assigned card nor the
/// pick (a safer round's lineup), any number of them. `dealt` is a surface
/// round's dealt structure other than the lead; it has no ping kind, so its
/// ping carries `option` alone. Canon is the `canonCard`, never an option.
pub const CARD_KINDS: [&str; 5] = ["assigned", "pick", "challenger", "grounded", "dealt"];

/// The highest re-roll round the choice ping reports.
pub const MAX_REROLL: usize = 8;

/// The highest zero-based card position the choice ping reports.
pub const MAX_OPTION: usize = 15;

pub fn api_base(env: &Env) -> String {
    let base = env.get("IMPECCABLE_API_URL").filter(|v| !v.is_empty()).cloned().unwrap_or_else(|| "https://impeccable.style/api".to_string());
    base.strip_suffix('/').unwrap_or(&base).to_string()
}

/// `IMPECCABLE_API_TIMEOUT` in ms (default 4000): one budget for the API
/// calls a run makes.
pub fn api_timeout(env: &Env) -> Duration {
    let ms = env.get("IMPECCABLE_API_TIMEOUT").filter(|v| !v.is_empty()).map(|v| crate::critique_storage::js_number(v)).unwrap_or(4000.0);
    let ms = if ms.is_nan() { 0.0 } else { ms.max(0.0) };
    Duration::from_millis(ms as u64)
}

/// An opt-out variable is set when it is non-empty and not `0` or `false`
/// (any case): `DO_NOT_TRACK=1` opts out, `DO_NOT_TRACK=0` does not.
pub fn env_opts_out(v: Option<&String>) -> bool {
    v.map(|v| v.trim()).is_some_and(|v| !v.is_empty() && v != "0" && !v.eq_ignore_ascii_case("false"))
}

/// The user-level config, `~/.impeccable/config.json`, where
/// `impeccable telemetry off` records `"telemetry": false`.
pub fn user_config_path(env: &Env) -> String {
    jsp::join(&[&crate::util::homedir(env), ".impeccable", "config.json"])
}

fn config_says_off(path: &str) -> bool {
    safe_read(path).and_then(|t| serde_json::from_str::<Value>(&t).ok()).and_then(|v| v.get("telemetry").and_then(Value::as_bool)) == Some(false)
}

/// Why telemetry is off, or `None` when it is on: `DO_NOT_TRACK` or
/// `IMPECCABLE_NO_TELEMETRY` (`env_opts_out`), `"telemetry": false` in the
/// user config, or in the project's `.impeccable/config.json` /
/// `config.local.json` (a project may opt everyone out; nothing opts back in
/// over an off anywhere).
pub fn opt_out_reason(env: &Env, cwd: &str) -> Option<String> {
    for var in ["DO_NOT_TRACK", "IMPECCABLE_NO_TELEMETRY"] {
        if env_opts_out(env.get(var)) {
            return Some(format!("{} is set", var));
        }
    }
    let user = user_config_path(env);
    if config_says_off(&user) {
        return Some(format!("\"telemetry\": false in {}", impeccable_common::jsp::to_posix(&user)));
    }
    // The project config is read where `context` reads its defaults: the
    // working directory, the resolved project root, then the repo root.
    let project = crate::context::resolve_project(cwd, &crate::target_args::TargetOptions::default(), env);
    let mut roots: Vec<String> = Vec::new();
    for r in [cwd, project.project_root.as_str(), project.repo_root.as_str()] {
        if r.is_empty() {
            continue;
        }
        let a = jsp::resolve(r, &[]);
        if !roots.contains(&a) {
            roots.push(a);
        }
    }
    for root in &roots {
        for name in ["config.local.json", "config.json"] {
            let p = jsp::join(&[root, ".impeccable", name]);
            if config_says_off(&p) {
                // Shown with forward slashes on every platform, like every
                // path the engine prints.
                let shown = jsp::relative(cwd, cwd, &p);
                return Some(format!("\"telemetry\": false in {}", impeccable_common::jsp::to_posix(if shown.is_empty() { &p } else { &shown })));
            }
        }
    }
    None
}

pub fn telemetry_disabled(env: &Env, cwd: &str) -> bool {
    opt_out_reason(env, cwd).is_some()
}

/// Sent on the roll request when telemetry is off: the roll still happens
/// (it is the feature), and the server records nothing for it.
pub const TELEMETRY_HEADER: &str = "X-Impeccable-Telemetry";

pub fn agent(timeout: Duration) -> ureq::Agent {
    crate::http::agent_builder().timeout_connect(timeout).timeout(timeout).build()
}

pub const CLIENT_HEADER: &str = "X-Impeccable-Client";

fn version_token(v: &str) -> bool {
    !v.is_empty() && v.len() <= 32 && v.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'+' | b'-'))
}

/// `impeccable/<version>[ <channel>]`, matching
/// `^impeccable/[0-9A-Za-z.+-]{1,32}( [a-z]{1,16})?$`. The version is the
/// installed skill's (SKILL.md frontmatter, what `/api/version` compares)
/// when the engine can read it, else the engine's own as `<engine>+engine`.
/// The channel is `IMPECCABLE_TELEMETRY_CHANNEL` when it is 1 to 16 lowercase
/// letters (`test` in this repo's tests and CI), else absent.
pub fn client_header(env: &Env, cwd: &str) -> String {
    let skill = crate::context_cli::installed_skill_version(env, cwd).filter(|v| version_token(v));
    let version = skill.unwrap_or_else(|| format!("{}+engine", env!("CARGO_PKG_VERSION")));
    let channel = env
        .get("IMPECCABLE_TELEMETRY_CHANNEL")
        .filter(|c| !c.is_empty() && c.len() <= 16 && c.bytes().all(|b| b.is_ascii_lowercase()))
        .map(|c| format!(" {}", c))
        .unwrap_or_default();
    format!("impeccable/{}{}", version, channel)
}

/// A roll response's `poolRevision` when it is the 12 lowercase hex the API
/// sends; anything else is not recorded or forwarded.
pub fn valid_pool_revision(v: &str) -> bool {
    v.len() == 12 && v.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}

/// A roll response's `handId` (32 lowercase hex, the server's opaque name
/// for the exact hand) is kept and forwarded only in that shape; older
/// servers omit it and nothing is sent.
pub fn valid_hand_id(v: &str) -> bool {
    v.len() == 32 && v.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}

// ---- seed ledger -------------------------------------------------------------

/// One API-dealt round as concept-seed recorded it.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct SeedRound {
    pub scope: String,
    pub reroll: usize,
    pub mode: Option<String>,
    pub register: Option<String>,
    pub pool_revision: Option<String>,
    pub hand_id: Option<String>,
    /// The catalog ids the round printed as challengers, in print order.
    pub dealt: Vec<String>,
    /// The round's choice state: `pending` while the page's send is in
    /// flight, `picker` or `agent` once a send was confirmed.
    pub recorded: Option<String>,
    /// When the pending send began (epoch ms), while `recorded` is `pending`.
    pub pending_at: Option<f64>,
    /// 32 random hex naming this round's choice report, the same for the
    /// page's and the agent's send, so the server can drop a duplicate.
    pub ping_id: Option<String>,
}

impl SeedRound {
    /// A confirmed send: the agent's rerun for this round is a no-op.
    pub fn confirmed(&self) -> bool {
        matches!(self.recorded.as_deref(), Some("picker") | Some("agent"))
    }
}

/// The salt seed references are computed under (`impeccable_common::seed`).
/// `None` when no valid salt can be persisted on this machine: then there
/// is no seed reference at all, never an unsalted one.
pub fn seed_salt(env: &Env, cwd: &str) -> Option<String> {
    impeccable_common::seed::salt(&crate::util::homedir(env), Some(cwd), env.get("IMPECCABLE_SEED_SALT").map(String::as_str))
}

/// Every valid salt this machine keeps (home and project): a reference made
/// under any of them resolves.
pub fn seed_salts(env: &Env, cwd: &str) -> Vec<String> {
    impeccable_common::seed::existing_salts(&crate::util::homedir(env), Some(cwd), env.get("IMPECCABLE_SEED_SALT").map(String::as_str))
}

/// The seed ledger of one project directory: `.impeccable/questions/seeds/
/// <reference hex>.json`, `{"key", "rounds"?: {"<reroll>": {...}}}`. The key
/// entry is what lets a reference stand for its key on this machine and is
/// never pruned; rounds exist only while telemetry is on and are pruned after
/// 30 days. Every update is a read-modify-write under a per-file lock, so the
/// page's send and a concurrent roll of the next round never lose each
/// other's writes.
pub struct Ledger {
    cwd: String,
    salt: Option<String>,
    /// Every salt references may have been made under, `salt` first.
    salts: Vec<String>,
    /// A key this run generated itself: it cannot have a ledger, so the
    /// locator skips its search (`for_fresh_key`).
    fresh: Option<String>,
}

/// Ledger rounds older than this are pruned when a ledger is written; the
/// key behind the reference stays.
const SEED_TTL_MS: f64 = 30.0 * 24.0 * 60.0 * 60.0 * 1000.0;

/// A lock older than this belongs to a process that died holding it.
const LOCK_STALE_MS: u128 = 10_000;

/// How long a ledger update waits for the lock before giving up (best
/// effort: the feature never fails on its ledger).
const LOCK_WAIT_MS: u128 = 3_000;

fn unique_suffix() -> String {
    use std::sync::atomic::{AtomicU64, Ordering};
    static COUNTER: AtomicU64 = AtomicU64::new(0);
    let n = COUNTER.fetch_add(1, Ordering::Relaxed);
    let t = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_nanos()).unwrap_or(0);
    format!("{}-{}-{}", std::process::id(), n, t)
}

struct LockGuard(String);

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

fn lock(path: &str) -> Option<LockGuard> {
    let lock = format!("{}.lock", path);
    let start = std::time::Instant::now();
    loop {
        match std::fs::OpenOptions::new().write(true).create_new(true).open(&lock) {
            Ok(_) => return Some(LockGuard(lock)),
            // Windows answers a create racing a delete of the same name with
            // access denied rather than exists: both mean another holder.
            Err(e) if matches!(e.kind(), std::io::ErrorKind::AlreadyExists | std::io::ErrorKind::PermissionDenied) => {
                // Every pass checks the overall deadline first, the stale
                // branch included: a lock that cannot be removed (Windows
                // keeps a deleted file delete-pending; a read-only folder)
                // must not spin forever. Giving up never blocks a flow.
                if start.elapsed().as_millis() > LOCK_WAIT_MS {
                    return None;
                }
                let stale = std::fs::metadata(&lock).ok().and_then(|m| m.modified().ok()).and_then(|t| t.elapsed().ok()).is_some_and(|age| age.as_millis() > LOCK_STALE_MS);
                if stale && std::fs::remove_file(&lock).is_ok() {
                    continue;
                }
                std::thread::sleep(Duration::from_millis(15));
            }
            Err(_) => return None,
        }
    }
}

fn round_from(v: &Value, reroll: usize) -> SeedRound {
    let s = |k: &str| v.get(k).and_then(Value::as_str).map(str::to_string);
    SeedRound {
        scope: s("scope").unwrap_or_default(),
        reroll,
        mode: s("mode"),
        register: s("register"),
        pool_revision: s("poolRevision").filter(|p| valid_pool_revision(p)),
        hand_id: s("handId").filter(|h| valid_hand_id(h)),
        dealt: v.get("dealt").and_then(Value::as_array).map(|a| a.iter().filter_map(Value::as_str).map(str::to_string).collect()).unwrap_or_default(),
        recorded: s("recorded"),
        pending_at: v.get("pendingAt").and_then(Value::as_f64),
        ping_id: s("pingId").filter(|p| valid_hand_id(p)),
    }
}

impl Ledger {
    pub fn new(env: &Env, cwd: &str) -> Ledger {
        let salt = seed_salt(env, cwd);
        let mut salts: Vec<String> = salt.iter().cloned().collect();
        for s in seed_salts(env, cwd) {
            if !salts.contains(&s) {
                salts.push(s);
            }
        }
        Ledger { cwd: cwd.to_string(), salt, salts, fresh: None }
    }

    fn dir(&self) -> String {
        jsp::join(&[&self.cwd, ".impeccable", "questions", "seeds"])
    }

    /// The key's ledger, located once by the shared rule
    /// (`impeccable_common::seed::locate`): every operation, the printed
    /// reference and resolution all derive from this one answer.
    fn locate(&self, key: &str) -> impeccable_common::seed::Located {
        if self.fresh.as_deref() == Some(key) {
            return impeccable_common::seed::locate_fresh(&self.cwd, self.salt.as_deref(), key);
        }
        impeccable_common::seed::locate(&self.cwd, self.salt.as_deref(), &self.salts, key)
    }

    /// Marks `key` as one this run just generated (no `--from`, no
    /// `IMPECCABLE_CONCEPT_SEED`): 128 random bits have no ledger, so no
    /// name check or folder scan is spent on it.
    pub fn for_fresh_key(mut self, key: &str, fresh: bool) -> Ledger {
        if fresh {
            self.fresh = Some(key.to_string());
        }
        self
    }

    fn file(&self, key: &str) -> String {
        self.locate(key).path.to_string_lossy().into_owned()
    }

    /// The seed reference committed files record instead of `key`: the
    /// reference of the key's existing ledger, under whichever salt it was
    /// made, or for a new key the primary salt's. `None` when this machine
    /// has no salt and the key has no salted ledger.
    pub fn reference(&self, key: &str) -> Option<String> {
        self.locate(key).reference
    }

    fn read_file(path: &str) -> Option<Map<String, Value>> {
        safe_read(path).and_then(|t| serde_json::from_str::<Value>(&t).ok()).and_then(|v| v.as_object().cloned())
    }

    fn write_file(&self, path: &str, ledger: &Map<String, Value>) {
        let temp = format!("{}.tmp-{}", path, unique_suffix());
        if std::fs::write(&temp, json_compact(&Value::Object(ledger.clone()))).is_err() {
            let _ = std::fs::remove_file(&temp);
            return;
        }
        // A rename over a file an unlocked reader has open can fail for a
        // moment on Windows; retry briefly before giving up.
        for attempt in 0..20 {
            if std::fs::rename(&temp, path).is_ok() {
                return;
            }
            if attempt < 19 {
                std::thread::sleep(Duration::from_millis(10));
            }
        }
        let _ = std::fs::remove_file(&temp);
    }

    /// Read, change, write `key`'s ledger under its lock. The questions
    /// directory's ignore file goes in before anything is written.
    fn update<R>(&self, key: &str, f: impl FnOnce(&mut Map<String, Value>) -> R) -> Option<R> {
        if std::fs::create_dir_all(self.dir()).is_err() {
            return None;
        }
        crate::serve_question::ignore_questions_dir(&jsp::join(&[&self.cwd, ".impeccable", "questions"]));
        let located = self.locate(key);
        let path = located.path.to_string_lossy().into_owned();
        let _guard = lock(&path)?;
        let mut ledger = Self::read_file(&path).unwrap_or_default();
        // A ledger made with no salt says so, so it never yields a reference.
        if !located.exists && located.reference.is_none() {
            ledger.insert("unsalted".into(), Value::Bool(true));
        }
        let before = ledger.clone();
        let out = f(&mut ledger);
        if ledger != before {
            self.write_file(&path, &ledger);
        }
        Some(out)
    }

    /// A seed value as given to `--from`: a key stands as itself; a
    /// reference resolves to the key this machine recorded for it. `Err`
    /// names a reference this machine has no record of.
    pub fn resolve(&self, v: &str) -> Result<String, String> {
        if impeccable_common::seed::parse_reference(v).is_none() {
            return Ok(v.to_string());
        }
        // The ledger is named by the reference itself, whatever salt made it.
        impeccable_common::seed::resolve(&self.cwd, v).ok_or_else(|| v.to_string())
    }

    /// Records the key behind a reference, for every roll whatever the
    /// telemetry setting: it is what makes the reference usable.
    pub fn record_key(&self, key: &str) {
        self.update(key, |l| {
            l.insert("key".into(), Value::String(key.to_string()));
        });
        self.prune();
    }

    /// Records an API-dealt round, replacing an earlier record of the same
    /// round (a reproduced roll is a new presentation, so it gets a fresh
    /// `pingId` and no sent state). Telemetry only.
    pub fn record_round(&self, key: &str, round: &SeedRound) {
        let ping_id = impeccable_common::seed::random_hex32();
        self.update(key, |l| {
            l.insert("key".into(), Value::String(key.to_string()));
            let rounds = l.entry("rounds").or_insert_with(|| Value::Object(Map::new()));
            if !rounds.is_object() {
                *rounds = Value::Object(Map::new());
            }
            let mut r = Map::new();
            r.insert("scope".into(), Value::String(round.scope.clone()));
            if let Some(m) = &round.mode {
                r.insert("mode".into(), Value::String(m.clone()));
            }
            if let Some(reg) = &round.register {
                r.insert("register".into(), Value::String(reg.clone()));
            }
            if let Some(p) = round.pool_revision.as_ref().filter(|p| valid_pool_revision(p)) {
                r.insert("poolRevision".into(), Value::String(p.clone()));
            }
            if let Some(h) = round.hand_id.as_ref().filter(|h| valid_hand_id(h)) {
                r.insert("handId".into(), Value::String(h.clone()));
            }
            r.insert("dealt".into(), json!(round.dealt));
            if let Some(p) = &ping_id {
                r.insert("pingId".into(), Value::String(p.clone()));
            }
            rounds.as_object_mut().unwrap().insert(round.reroll.to_string(), Value::Object(r));
        });
        self.prune();
    }

    /// The recorded round `reroll` for `key`, or the latest recorded round
    /// when `reroll` is `None` (a choice resolves on the round last dealt).
    pub fn round(&self, key: &str, reroll: Option<usize>) -> Option<SeedRound> {
        let ledger = Self::read_file(&self.file(key))?;
        let rounds = ledger.get("rounds")?.as_object()?;
        let n = match reroll {
            Some(n) => n,
            None => rounds.keys().filter_map(|k| k.parse::<usize>().ok()).max()?,
        };
        rounds.get(&n.to_string()).map(|v| round_from(v, n))
    }

    fn with_round<R>(&self, key: &str, reroll: usize, f: impl FnOnce(&mut Map<String, Value>) -> R) -> Option<R> {
        self.update(key, |l| {
            let r = l.get_mut("rounds").and_then(Value::as_object_mut).and_then(|rs| rs.get_mut(&reroll.to_string())).and_then(Value::as_object_mut)?;
            Some(f(r))
        })
        .flatten()
    }

    /// The page's claim on a round before it sends: a round with no choice
    /// state becomes `pending`. Returns the round (with its `pingId`) when
    /// the claim took; `None` when the round is unknown or already claimed.
    pub fn claim(&self, key: &str, reroll: usize) -> Option<SeedRound> {
        self.with_round(key, reroll, |r| {
            if r.contains_key("recorded") {
                return None;
            }
            r.insert("recorded".into(), Value::String("pending".into()));
            r.insert("pendingAt".into(), Value::from(crate::util::now_ms() as u64));
            Some(round_from(&Value::Object(r.clone()), reroll))
        })
        .flatten()
    }

    /// Whether a completion for the report `ping_id` still belongs to this
    /// round: a reproduced round gets a new `pingId`, so a send for the old
    /// one that finishes late touches nothing.
    fn same_report(r: &Map<String, Value>, ping_id: Option<&str>) -> bool {
        r.get("pingId").and_then(Value::as_str) == ping_id
    }

    /// A confirmed send of the report `ping_id` by `by`: the round's later
    /// reruns are no-ops. Ignored when the round now names another report.
    pub fn confirm(&self, key: &str, reroll: usize, by: &str, ping_id: Option<&str>) {
        self.with_round(key, reroll, |r| {
            if Self::same_report(r, ping_id) {
                r.insert("recorded".into(), Value::String(by.to_string()));
                r.remove("pendingAt");
            }
        });
    }

    /// A send of the report `ping_id` that failed: a still-pending round
    /// goes back to no state, so the agent's rerun sends it. Ignored when
    /// the round now names another report.
    pub fn release(&self, key: &str, reroll: usize, ping_id: Option<&str>) {
        self.with_round(key, reroll, |r| {
            if Self::same_report(r, ping_id) && r.get("recorded").and_then(Value::as_str) == Some("pending") {
                r.remove("recorded");
                r.remove("pendingAt");
            }
        });
    }

    /// Drops the rounds of ledgers untouched for `SEED_TTL_MS`, keeping the
    /// key so their references keep resolving.
    fn prune(&self) {
        let Ok(entries) = std::fs::read_dir(self.dir()) else { return };
        for e in entries.flatten() {
            let path = e.path().to_string_lossy().into_owned();
            if !path.ends_with(".json") {
                continue;
            }
            let old = e.metadata().ok().and_then(|m| m.modified().ok()).and_then(|t| t.elapsed().ok()).is_some_and(|age| age.as_millis() as f64 > SEED_TTL_MS);
            if !old || !Self::read_file(&path).is_some_and(|l| l.contains_key("rounds")) {
                continue;
            }
            if let Some(_guard) = lock(&path) {
                // Re-checked under the lock: another process may have written
                // a round, or claimed one, since the unlocked look above.
                let still_old = std::fs::metadata(&path).ok().and_then(|m| m.modified().ok()).and_then(|t| t.elapsed().ok()).is_some_and(|age| age.as_millis() as f64 > SEED_TTL_MS);
                if let Some(mut l) = Self::read_file(&path).filter(|_| still_old) {
                    let pending = l.get("rounds").and_then(Value::as_object).is_some_and(|rs| rs.values().any(|r| r.get("recorded").and_then(Value::as_str) == Some("pending")));
                    if !pending && l.remove("rounds").is_some() {
                        self.write_file(&path, &l);
                    }
                }
            }
        }
    }
}

// ---- the choice ping ---------------------------------------------------------

/// One `/api/chosen` body. `source` is `agent` for the agent-run `--kind`
/// command and `picker` when the decision page's server sends it;
/// `kind_source` (picker only) says whether the card declared its kind
/// (`explicit`) or the engine read it from older payload conventions
/// (`inferred`).
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ChoicePing {
    pub chosen_id: Option<String>,
    pub key: Option<String>,
    pub scope: Option<String>,
    pub mode: Option<String>,
    pub kind: Option<String>,
    pub register: Option<String>,
    /// The chosen card's zero-based position in the payload's options.
    pub option: Option<usize>,
    pub reroll: Option<usize>,
    pub pool_revision: Option<String>,
    pub hand_id: Option<String>,
    pub ping_id: Option<String>,
    pub kind_source: Option<&'static str>,
    pub source: &'static str,
}

impl ChoicePing {
    /// The JSON body, keys in a fixed order, absent values omitted.
    pub fn body(&self) -> Value {
        let mut body = Map::new();
        let mut put = |k: &str, v: &Option<String>| {
            if let Some(v) = v {
                body.insert(k.into(), Value::String(v.clone()));
            }
        };
        put("chosenId", &self.chosen_id);
        put("key", &self.key);
        put("scope", &self.scope);
        put("mode", &self.mode);
        put("kind", &self.kind);
        put("register", &self.register);
        if let Some(o) = self.option.filter(|o| *o <= MAX_OPTION) {
            body.insert("option".into(), Value::from(o));
        }
        if let Some(r) = self.reroll.filter(|r| *r <= MAX_REROLL) {
            body.insert("reroll".into(), Value::from(r));
        }
        if let Some(p) = self.pool_revision.as_ref().filter(|p| valid_pool_revision(p)) {
            body.insert("poolRevision".into(), Value::String(p.clone()));
        }
        if let Some(h) = self.hand_id.as_ref().filter(|h| valid_hand_id(h)) {
            body.insert("handId".into(), Value::String(h.clone()));
        }
        if let Some(p) = self.ping_id.as_ref().filter(|p| valid_hand_id(p)) {
            body.insert("pingId".into(), Value::String(p.clone()));
        }
        if let Some(k) = self.kind_source {
            body.insert("kindSource".into(), Value::String(k.to_string()));
        }
        body.insert("source".into(), Value::String(self.source.to_string()));
        Value::Object(body)
    }
}

/// POSTs the ping to `/api/chosen` within `timeout`. Never fails the
/// caller: any error is a false.
pub fn send_choice(env: &Env, cwd: &str, ping: &ChoicePing, timeout: Duration) -> bool {
    if timeout.is_zero() {
        return false;
    }
    let url = format!("{}/chosen", api_base(env));
    agent(timeout)
        .post(&url)
        .set("Content-Type", "application/json")
        .set(CLIENT_HEADER, &client_header(env, cwd))
        .send_string(&json_compact(&ping.body()))
        .is_ok()
}

// ---- the picker's choice -----------------------------------------------------

fn card_text<'a>(card: &'a Value, k: &str) -> Option<&'a str> {
    card.get(k).and_then(Value::as_str).map(str::trim).filter(|s| !s.is_empty())
}

fn is_pick_kicker(kicker: &str) -> bool {
    let k = kicker.to_uppercase().replace('\u{2019}', "'");
    k == "IMPECCABLE'S PICK"
}

/// The single dealt catalog world a challenger card draws from, matched by
/// its card images: the same board or hero URL the roll printed, or the
/// workspace copy serve-question keeps of it (`<id>-board.<ext>` /
/// `<id>-hero.<ext>`). `None` when no world or more than one matches.
fn matched_world(card: &Value, dealt: &[Value]) -> Option<String> {
    let images: Vec<&str> = ["hero", "board"].iter().filter_map(|k| card_text(card, k)).collect();
    let mut found: Vec<String> = Vec::new();
    for w in dealt {
        let Some(id) = w.get("id").and_then(Value::as_str) else { continue };
        let urls: Vec<&str> = ["hero", "board"].iter().filter_map(|k| w.get(*k).and_then(Value::as_str)).collect();
        let hit = images.iter().any(|img| {
            if urls.contains(img) {
                return true;
            }
            let file = img.replace('\\', "/");
            let name = file.rsplit('/').next().unwrap_or("");
            let stem = name.rsplit_once('.').map(|(s, _)| s).unwrap_or(name);
            !img.contains("://") && (stem == format!("{}-hero", id) || stem == format!("{}-board", id))
        });
        if hit && !found.iter().any(|f| f == id) {
            found.push(id.to_string());
        }
    }
    (found.len() == 1).then(|| found.remove(0))
}

/// The choice ping for an answer on a decision page. `seed` is the hand's
/// `seed` record (an API-dealt roll the page took, either scope); `payload`
/// the round the page served; `option_id` the answer's; `steer` the
/// register a re-roll answer carries.
///
/// - A re-roll answer is the hand rejected: kind `reroll`, `register` the
///   steer when there is one, `reroll` the round rejected.
/// - `canon` (the reserved option id, direction rounds only): kind `canon`.
/// - An option card sends its declared `kind` (`kindSource: explicit`):
///   `assigned`, `pick`, `challenger` with its `catalogId` as `chosenId`
///   only when that id was dealt this round, and `dealt` with no kind.
/// - A card with no valid `kind` (a payload from older skill text) falls
///   back to the old conventions (`kindSource: inferred`): a `verdict` card
///   is a challenger, its `chosenId` the one dealt world its card images
///   match; kicker `IMPECCABLE'S PICK` is the pick on a plain direction
///   round; kicker `THE ROLL`, or the lead card, is the assigned card on a
///   plain direction round and the dealt lead on a surface round. Anything
///   else sends no kind.
///
/// Every option-card ping carries `option`, the card's zero-based position,
/// so a choice with no kind is still recorded.
pub fn picker_choice(seed: &Value, payload: &Value, option_id: &str, steer: Option<&str>) -> Option<ChoicePing> {
    if seed.get("source").and_then(Value::as_str) != Some("api") {
        return None;
    }
    let scope = seed.get("scope").and_then(Value::as_str).filter(|s| *s == "direction" || *s == "surface")?;
    let key = seed.get("key").and_then(Value::as_str).filter(|k| !k.is_empty())?;
    let reroll = seed.get("reroll").and_then(Value::as_u64).map(|r| r as usize).filter(|r| *r <= MAX_REROLL)?;
    let valid_register = |r: &&str| *r == "safer" || *r == "bolder";
    let register = seed.get("register").and_then(Value::as_str).filter(valid_register);
    let dealt: Vec<Value> = seed.get("dealt").and_then(Value::as_array).cloned().unwrap_or_default();
    let dealt_id = |id: &str| dealt.iter().any(|w| w.get("id").and_then(Value::as_str) == Some(id));
    let s = |k: &str| seed.get(k).and_then(Value::as_str).map(str::to_string);
    let base = ChoicePing {
        key: Some(key.to_string()),
        scope: Some(scope.to_string()),
        mode: s("mode"),
        register: register.map(str::to_string),
        reroll: Some(reroll),
        pool_revision: s("poolRevision").filter(|p| valid_pool_revision(p)),
        hand_id: s("handId").filter(|h| valid_hand_id(h)),
        kind_source: Some("explicit"),
        source: "picker",
        ..Default::default()
    };
    match option_id {
        "" => return None,
        "reroll" => return Some(ChoicePing { kind: Some("reroll".into()), register: steer.filter(valid_register).map(str::to_string), ..base }),
        "canon" if scope == "direction" => return Some(ChoicePing { kind: Some("canon".into()), ..base }),
        "canon" => return None,
        _ => {}
    }
    let options: Vec<Value> = payload.get("options").and_then(Value::as_array).cloned().unwrap_or_default();
    let (index, card) = options.iter().enumerate().find(|(_, o)| o.get("id").and_then(Value::as_str) == Some(option_id))?;
    let option = Some(index).filter(|i| *i <= MAX_OPTION);
    let declared = card_text(card, "kind").filter(|k| CARD_KINDS.contains(k));
    if let Some(k) = declared {
        let (kind, chosen_id) = match k {
            "challenger" => (Some("challenger"), card_text(card, "catalogId").filter(|id| dealt_id(id)).map(str::to_string)),
            "dealt" => (None, None),
            other => (Some(other), None),
        };
        return Some(ChoicePing { kind: kind.map(str::to_string), chosen_id, option, ..base });
    }
    let kicker = card_text(card, "kicker");
    let lead = kicker.is_some_and(|k| k.eq_ignore_ascii_case("THE ROLL")) || index == 0;
    let (kind, chosen_id) = if card_text(card, "verdict").is_some() {
        (Some("challenger"), matched_world(card, &dealt))
    } else if scope == "surface" {
        (lead.then_some("assigned"), None)
    } else if register.is_some() {
        (None, None)
    } else if kicker.is_some_and(is_pick_kicker) {
        (Some("pick"), None)
    } else {
        (lead.then_some("assigned"), None)
    };
    Some(ChoicePing { kind: kind.map(str::to_string), chosen_id, option, kind_source: Some("inferred"), ..base })
}

// ---- `impeccable telemetry off|on|status` -------------------------------------

pub const PRIVACY_URL: &str = "https://impeccable.style/privacy";

fn status_line(env: &Env, cwd: &str) -> String {
    match opt_out_reason(env, cwd) {
        Some(reason) => format!("telemetry: off ({}). Rolls still work; the roll API is told not to record them, and no choice is sent.\n", reason),
        None => format!("telemetry: on. The roll request and the choice ping carry the seed key, scope, mode, round, pool revision, the card kind and catalog id that won, and the client version; never your project's names or code. Turn it off with `impeccable telemetry off`, DO_NOT_TRACK=1, or IMPECCABLE_NO_TELEMETRY=1. Details: {}\n", PRIVACY_URL),
    }
}

/// `impeccable telemetry off|on|status`: `off` records `"telemetry": false`
/// in the user config (`user_config_path`), `on` removes it, `status` says
/// whether telemetry is on and, when off, why. Other keys in the file are
/// kept.
pub fn run(args: &[String], io: &mut impeccable_common::Io) -> i32 {
    let env = io.env.clone();
    let cwd = io.cwd.to_string_lossy().into_owned();
    let path = user_config_path(&env);
    // A missing file is an empty config; one that does not parse to an
    // object is the user's to fix, never overwritten.
    let read = || -> Result<Map<String, Value>, String> {
        let Some(text) = safe_read(&path) else { return Ok(Map::new()) };
        match serde_json::from_str::<Value>(&text) {
            Ok(Value::Object(m)) => Ok(m),
            Ok(_) => Err(format!("{} is not a JSON object", impeccable_common::jsp::to_posix(&path))),
            Err(e) => Err(format!("{} is not valid JSON ({})", impeccable_common::jsp::to_posix(&path), e)),
        }
    };
    let write = |m: &Map<String, Value>| -> Result<(), String> {
        let dir = jsp::join(&[&crate::util::homedir(&env), ".impeccable"]);
        std::fs::create_dir_all(&dir)
            .and_then(|_| std::fs::write(&path, format!("{}\n", crate::util::json_pretty(&Value::Object(m.clone())))))
            .map_err(|e| format!("{}: {}", path, e))
    };
    match args.first().map(String::as_str) {
        Some("status") | None => {
            io.out(&status_line(&env, &cwd));
            0
        }
        Some(cmd @ ("off" | "on")) => {
            let mut m = match read() {
                Ok(m) => m,
                Err(e) => {
                    io.err(&format!("telemetry: {}; fix or remove it, then run `impeccable telemetry {}` again. Nothing was changed.\n", e, cmd));
                    return 1;
                }
            };
            if cmd == "off" {
                m.insert("telemetry".into(), Value::Bool(false));
            } else {
                m.remove("telemetry");
            }
            if let Err(e) = write(&m) {
                io.err(&format!("telemetry: could not write the user config ({})\n", e));
                return 1;
            }
            io.out(&status_line(&env, &cwd));
            0
        }
        Some(other) => {
            io.err(&format!("telemetry: unknown command \"{}\"; use off, on, or status\n", other));
            1
        }
    }
}

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

    fn temp_dir(name: &str) -> String {
        let dir = std::env::temp_dir().join(format!("impeccable-telemetry-{}-{}", name, std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        dir.to_string_lossy().into_owned()
    }

    fn env(pairs: &[(&str, &str)]) -> Env {
        pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect()
    }

    fn header_ok(h: &str) -> bool {
        let re = regex::Regex::new(r"^impeccable/[0-9A-Za-z.+-]{1,32}( [a-z]{1,16})?$").unwrap();
        re.is_match(h)
    }

    #[test]
    fn client_header_names_the_skill_version_else_the_engine_and_the_channel() {
        let dir = temp_dir("header");
        let skill = format!("{}/skill", dir);
        std::fs::create_dir_all(&skill).unwrap();
        let e = env(&[("IMPECCABLE_SKILL_DIR", &skill)]);
        let h = client_header(&e, &dir);
        assert_eq!(h, format!("impeccable/{}+engine", env!("CARGO_PKG_VERSION")));
        assert!(header_ok(&h), "{h}");
        std::fs::write(format!("{}/SKILL.md", skill), "---\nname: impeccable\nversion: 4.5.2\n---\n# x\n").unwrap();
        assert_eq!(client_header(&e, &dir), "impeccable/4.5.2");
        let e = env(&[("IMPECCABLE_SKILL_DIR", &skill), ("IMPECCABLE_TELEMETRY_CHANNEL", "test")]);
        let h = client_header(&e, &dir);
        assert_eq!(h, "impeccable/4.5.2 test");
        assert!(header_ok(&h), "{h}");
        // A channel that does not fit the format is dropped, never sent malformed.
        for bad in ["Test", "te st", "abcdefghijklmnopq", "t3st"] {
            let e = env(&[("IMPECCABLE_SKILL_DIR", &skill), ("IMPECCABLE_TELEMETRY_CHANNEL", bad)]);
            assert_eq!(client_header(&e, &dir), "impeccable/4.5.2", "{bad}");
        }
        // A frontmatter version outside the token alphabet falls back to the engine.
        std::fs::write(format!("{}/SKILL.md", skill), "---\nversion: 4.5 beta\n---\n").unwrap();
        assert!(client_header(&env(&[("IMPECCABLE_SKILL_DIR", &skill)]), &dir).ends_with("+engine"));
    }

    pub(crate) fn test_ledger(cwd: &str) -> Ledger {
        Ledger::new(&env(&[("IMPECCABLE_SEED_SALT", "test-salt")]), cwd)
    }

    fn round(n: usize, dealt: &[&str]) -> SeedRound {
        SeedRound {
            scope: "direction".into(),
            reroll: n,
            mode: Some("persuade".into()),
            pool_revision: Some("0123456789ab".into()),
            hand_id: Some("00112233445566778899aabbccddeeff".into()),
            dealt: dealt.iter().map(|s| s.to_string()).collect(),
            ..Default::default()
        }
    }

    #[test]
    fn ledger_rounds_carry_a_ping_id_and_move_through_pending_to_confirmed() {
        let cwd = temp_dir("ledger");
        let l = test_ledger(&cwd);
        assert_eq!(l.round("k1", None), None);
        l.record_round("k1", &round(0, &["a", "b"]));
        l.record_round("k1", &round(1, &["c"]));
        assert_eq!(l.round("k1", None).unwrap().dealt, vec!["c"]);
        let r0 = l.round("k1", Some(0)).unwrap();
        assert_eq!((r0.dealt.clone(), r0.recorded.clone()), (vec!["a".to_string(), "b".to_string()], None));
        let ping_id = r0.ping_id.clone().unwrap();
        assert!(valid_hand_id(&ping_id), "{ping_id}");
        assert_ne!(l.round("k1", Some(1)).unwrap().ping_id.unwrap(), ping_id, "one id per round");
        assert_eq!(l.round("k1", Some(5)), None);
        // The page claims, the claim is exclusive, a failure releases it.
        let claimed = l.claim("k1", 0).unwrap();
        assert_eq!(claimed.ping_id.as_deref(), Some(ping_id.as_str()));
        assert_eq!(l.claim("k1", 0), None);
        let pending = l.round("k1", Some(0)).unwrap();
        assert!(pending.recorded.as_deref() == Some("pending") && pending.pending_at.is_some() && !pending.confirmed());
        let id = Some(ping_id.as_str());
        l.release("k1", 0, id);
        assert_eq!(l.round("k1", Some(0)).unwrap().recorded, None);
        // A confirmed send is final; release never undoes it.
        l.claim("k1", 0).unwrap();
        l.confirm("k1", 0, "picker", id);
        l.release("k1", 0, id);
        let done = l.round("k1", Some(0)).unwrap();
        assert!(done.confirmed() && done.pending_at.is_none(), "{done:?}");
        assert_eq!(l.round("k1", Some(0)).unwrap().ping_id.as_deref(), Some(ping_id.as_str()));
        // Malformed values are never stored.
        let mut r = round(2, &[]);
        r.pool_revision = Some("NOT-HEX".into());
        r.hand_id = Some("00112233445566778899AABBCCDDEEFF".into());
        l.record_round("k1", &r);
        let back = l.round("k1", Some(2)).unwrap();
        assert_eq!((back.pool_revision, back.hand_id), (None, None));
        // Files are named by the reference's hex and hold no time but a pending send's.
        l.record_round("../Evil Key", &round(0, &["x"]));
        for e in std::fs::read_dir(format!("{}/.impeccable/questions/seeds", cwd)).unwrap().flatten() {
            let name = e.file_name().to_string_lossy().into_owned();
            assert!(name.len() == 21 && name.ends_with(".json") && !name.contains("k1") && !name.contains("Evil"), "{name}");
            assert!(!std::fs::read_to_string(e.path()).unwrap().contains("\"at\""));
        }
        assert_eq!(l.resolve(&l.reference("../Evil Key").unwrap()).unwrap(), "../Evil Key");
        assert_eq!(std::fs::read_to_string(format!("{}/.impeccable/questions/.gitignore", cwd)).unwrap(), format!("{}\n*\n", impeccable_common::git::RUNTIME_IGNORE_HEADER));
    }

    #[test]
    fn a_late_completion_for_a_replaced_round_changes_nothing() {
        let cwd = temp_dir("ledger-late");
        let l = test_ledger(&cwd);
        l.record_round("k1", &round(0, &["a"]));
        let old = l.claim("k1", 0).unwrap().ping_id;
        // The round is reproduced (a new presentation, a new report) while the
        // old send is still in flight.
        l.record_round("k1", &round(0, &["a"]));
        let fresh = l.round("k1", Some(0)).unwrap();
        assert_ne!(fresh.ping_id, old);
        // The old send finishing, either way, leaves the new round alone.
        l.confirm("k1", 0, "picker", old.as_deref());
        assert_eq!(l.round("k1", Some(0)).unwrap().recorded, None, "a late success does not record the new round");
        let new_claim = l.claim("k1", 0).unwrap();
        l.release("k1", 0, old.as_deref());
        assert_eq!(l.round("k1", Some(0)).unwrap().recorded.as_deref(), Some("pending"), "a late failure does not clear the new claim");
        l.confirm("k1", 0, "picker", new_claim.ping_id.as_deref());
        assert!(l.round("k1", Some(0)).unwrap().confirmed());
    }

    #[test]
    fn no_salt_means_no_reference_never_an_unsalted_one() {
        let cwd = temp_dir("no-salt");
        let home = format!("{}/home", cwd);
        std::fs::create_dir_all(format!("{}/.impeccable", home)).unwrap();
        std::fs::write(format!("{}/.impeccable/seed-salt", home), "corrupt").unwrap();
        let l = Ledger::new(&env(&[("HOME", home.as_str()), ("USERPROFILE", home.as_str())]), &cwd);
        assert_eq!(l.reference("k1"), None);
        assert_eq!(l.resolve(&impeccable_common::seed::reference("", "k1")), Err(impeccable_common::seed::reference("", "k1")), "an unsalted hash resolves to nothing");
        // Telemetry rounds still work by key.
        l.record_round("k1", &round(0, &["a"]));
        assert!(l.round("k1", Some(0)).is_some());
    }

    #[test]
    fn concurrent_ledger_updates_lose_nothing() {
        let cwd = temp_dir("ledger-race");
        let l = test_ledger(&cwd);
        for n in 0..8 {
            l.record_round("k1", &round(n, &["a"]));
        }
        // Eight threads, each claiming and confirming its own round of the
        // same file at once: every write survives the others.
        let handles: Vec<_> = (0..8)
            .map(|n| {
                let cwd = cwd.clone();
                std::thread::spawn(move || {
                    let l = test_ledger(&cwd);
                    let claimed = l.claim("k1", n).unwrap();
                    l.confirm("k1", n, "picker", claimed.ping_id.as_deref());
                })
            })
            .collect();
        for h in handles {
            h.join().unwrap();
        }
        for n in 0..8 {
            assert!(l.round("k1", Some(n)).unwrap().confirmed(), "round {n}");
        }
        let leftovers: Vec<String> = std::fs::read_dir(format!("{}/.impeccable/questions/seeds", cwd)).unwrap().flatten().map(|e| e.file_name().to_string_lossy().into_owned()).filter(|n| n.contains(".tmp-") || n.ends_with(".lock")).collect();
        assert!(leftovers.is_empty(), "{leftovers:?}");
    }

    #[test]
    fn a_stale_lock_is_taken_over() {
        let cwd = temp_dir("ledger-stale");
        let l = test_ledger(&cwd);
        l.record_key("k1");
        let lock_path = format!("{}.lock", l.file("k1"));
        std::fs::write(&lock_path, "").unwrap();
        let old = std::time::SystemTime::now() - Duration::from_secs(60);
        std::fs::File::options().write(true).open(&lock_path).unwrap().set_modified(old).unwrap();
        l.record_round("k1", &round(0, &[]));
        assert!(l.round("k1", Some(0)).is_some(), "a lock left by a dead process does not block");
    }

    #[test]
    fn pruning_keeps_the_key_behind_a_reference() {
        let cwd = temp_dir("ledger-prune");
        let l = test_ledger(&cwd);
        l.record_round("k1", &round(0, &["a"]));
        let path = l.file("k1");
        let old = std::time::SystemTime::now() - Duration::from_secs(40 * 24 * 3600);
        std::fs::File::options().write(true).open(&path).unwrap().set_modified(old).unwrap();
        // A pending send keeps its rounds even on an old file.
        l.claim("k1", 0).unwrap();
        std::fs::File::options().write(true).open(&path).unwrap().set_modified(old).unwrap();
        l.record_key("other");
        assert!(l.round("k1", Some(0)).is_some(), "a pending round is never pruned");
        let id = l.round("k1", Some(0)).unwrap().ping_id;
        l.release("k1", 0, id.as_deref());
        std::fs::File::options().write(true).open(&path).unwrap().set_modified(old).unwrap();
        l.record_key("other");
        assert_eq!(l.round("k1", None), None, "old rounds go");
        assert_eq!(l.resolve(&l.reference("k1").unwrap()).unwrap(), "k1", "the reference still resolves");
    }

    #[test]
    fn body_orders_fields_and_drops_out_of_range_values() {
        let p = ChoicePing {
            chosen_id: Some("w1".into()),
            key: Some("k".into()),
            scope: Some("direction".into()),
            mode: None,
            kind: Some("challenger".into()),
            register: Some("bolder".into()),
            option: Some(3),
            reroll: Some(2),
            pool_revision: Some("0123456789ab".into()),
            hand_id: Some("00112233445566778899aabbccddeeff".into()),
            ping_id: Some("ffeeddccbbaa99887766554433221100".into()),
            kind_source: Some("explicit"),
            source: "picker",
        };
        assert_eq!(json_compact(&p.body()), r#"{"chosenId":"w1","key":"k","scope":"direction","kind":"challenger","register":"bolder","option":3,"reroll":2,"poolRevision":"0123456789ab","handId":"00112233445566778899aabbccddeeff","pingId":"ffeeddccbbaa99887766554433221100","kindSource":"explicit","source":"picker"}"#);
        // A handId in any other shape (an older or odd server) is never sent.
        for bad in ["00112233445566778899AABBCCDDEEFF", "0011", "00112233445566778899aabbccddeeffaa", "zz112233445566778899aabbccddeeff"] {
            assert!(!valid_hand_id(bad), "{bad}");
        }
        let p = ChoicePing { reroll: Some(9), option: Some(16), pool_revision: Some("xyz".into()), hand_id: Some("0011".into()), source: "picker", ..Default::default() };
        assert_eq!(json_compact(&p.body()), r#"{"source":"picker"}"#);
    }

    fn seed(register: Option<&str>) -> Value {
        let mut s = json!({
            "key": "k1", "scope": "direction", "reroll": 1, "mode": "persuade", "source": "api", "poolRevision": "0123456789ab",
            "dealt": [
                { "id": "teletext-service", "board": "https://cards.test/teletext-service.webp", "hero": "https://cards.test/teletext-service-hero.webp" },
                { "id": "microfiche-reader", "board": "https://cards.test/microfiche-reader.webp", "hero": "https://cards.test/microfiche-reader-hero.webp" }
            ]
        });
        if let Some(r) = register {
            s["register"] = json!(r);
        }
        s
    }

    /// A page from older skill text: no card declares a kind.
    fn legacy_page() -> Value {
        json!({ "options": [
            { "id": "assigned", "label": "Fillmore", "hero": "https://cards.test/teletext-service-hero.webp" },
            { "id": "model-pick", "label": "Broadside", "kicker": "IMPECCABLE’S PICK" },
            { "id": "challenger-teletext", "verdict": "competitive", "hero": "https://cards.test/teletext-service-hero.webp" },
            { "id": "challenger-microfiche", "verdict": "declined", "hero": ".impeccable/mocks/worlds/microfiche-reader-hero.webp" },
            { "id": "challenger-own", "verdict": "wins", "hero": "https://elsewhere.test/x.webp" },
            { "id": "grounded-2", "label": "Another" }
        ], "canon": true })
    }

    fn explicit_page() -> Value {
        json!({ "options": [
            { "id": "a", "kind": "assigned" },
            { "id": "p", "kind": "pick", "kicker": "IMPECCABLE’S PICK" },
            { "id": "c1", "kind": "challenger", "catalogId": "teletext-service", "verdict": "competitive" },
            { "id": "c2", "kind": "challenger", "catalogId": "challenger-teletext", "verdict": "wins" },
            { "id": "d", "kind": "dealt" },
            { "id": "g", "kind": "grounded" }
        ], "canon": true })
    }

    /// (kind, chosenId, option, kindSource) of a ping.
    type Read = Option<(Option<String>, Option<String>, Option<usize>, Option<&'static str>)>;
    fn read(p: Option<ChoicePing>) -> Read {
        p.map(|p| (p.kind, p.chosen_id, p.option, p.kind_source))
    }
    fn r(kind: Option<&str>, id: Option<&str>, option: Option<usize>, src: &'static str) -> Read {
        Some((kind.map(str::to_string), id.map(str::to_string), option, Some(src)))
    }

    #[test]
    fn picker_sends_the_kind_each_card_declares() {
        let pg = explicit_page();
        for register in [None, Some("safer"), Some("bolder")] {
            let s = seed(register);
            let k = |id: &str| read(picker_choice(&s, &pg, id, None));
            assert_eq!(k("a"), r(Some("assigned"), None, Some(0), "explicit"), "{register:?}");
            assert_eq!(k("p"), r(Some("pick"), None, Some(1), "explicit"), "{register:?}");
            assert_eq!(k("c1"), r(Some("challenger"), Some("teletext-service"), Some(2), "explicit"));
            // An id that was not dealt never leaves the machine; the kind still goes.
            assert_eq!(k("c2"), r(Some("challenger"), None, Some(3), "explicit"));
            assert_eq!(k("canon"), r(Some("canon"), None, None, "explicit"));
            assert_eq!(k("g"), r(Some("grounded"), None, Some(5), "explicit"), "a safer lineup card");
            assert_eq!(k("nope"), None);
            assert_eq!(picker_choice(&s, &pg, "a", None).unwrap().register.as_deref(), register);
        }
        let p = picker_choice(&seed(None), &pg, "c1", None).unwrap();
        assert_eq!(json_compact(&p.body()), r#"{"chosenId":"teletext-service","key":"k1","scope":"direction","mode":"persuade","kind":"challenger","option":2,"reroll":1,"poolRevision":"0123456789ab","kindSource":"explicit","source":"picker"}"#);
    }

    #[test]
    fn a_reroll_answer_is_the_hand_rejected() {
        let s = seed(Some("safer"));
        let p = picker_choice(&s, &explicit_page(), "reroll", Some("bolder")).unwrap();
        assert_eq!(json_compact(&p.body()), r#"{"key":"k1","scope":"direction","mode":"persuade","kind":"reroll","register":"bolder","reroll":1,"poolRevision":"0123456789ab","kindSource":"explicit","source":"picker"}"#);
        let p = picker_choice(&s, &explicit_page(), "reroll", None).unwrap();
        assert_eq!(p.register, None, "a plain re-roll carries no register");
    }

    #[test]
    fn surface_rounds_send_the_lead_as_assigned_and_other_dealt_cards_by_position() {
        let mut s = seed(None);
        s["scope"] = json!("surface");
        let pg = json!({ "options": [{ "id": "s1", "kind": "assigned" }, { "id": "s2", "kind": "dealt" }, { "id": "s3", "kind": "challenger", "catalogId": "microfiche-reader" }] });
        assert_eq!(read(picker_choice(&s, &pg, "s1", None)), r(Some("assigned"), None, Some(0), "explicit"));
        assert_eq!(read(picker_choice(&s, &pg, "s2", None)), r(None, None, Some(1), "explicit"));
        assert_eq!(read(picker_choice(&s, &pg, "s3", None)), r(Some("challenger"), Some("microfiche-reader"), Some(2), "explicit"));
        assert_eq!(picker_choice(&s, &pg, "canon", None), None, "surface rounds have no canon");
        assert_eq!(json_compact(&picker_choice(&s, &pg, "s2", None).unwrap().body()), r#"{"key":"k1","scope":"surface","mode":"persuade","option":1,"reroll":1,"poolRevision":"0123456789ab","kindSource":"explicit","source":"picker"}"#);
        // Older surface payloads: the lead is inferred, the rest go by position.
        let legacy = json!({ "options": [{ "id": "s1", "kicker": "THE ROLL" }, { "id": "s2" }] });
        assert_eq!(read(picker_choice(&s, &legacy, "s1", None)), r(Some("assigned"), None, Some(0), "inferred"));
        assert_eq!(read(picker_choice(&s, &legacy, "s2", None)), r(None, None, Some(1), "inferred"));
    }

    #[test]
    fn older_payloads_fall_back_to_the_conventions_marked_inferred() {
        let s = seed(None);
        let pg = legacy_page();
        let k = |id: &str| read(picker_choice(&s, &pg, id, None));
        // The assigned card may wear a catalog image; it is still the assigned card, with no id.
        assert_eq!(k("assigned"), r(Some("assigned"), None, Some(0), "inferred"));
        assert_eq!(k("model-pick"), r(Some("pick"), None, Some(1), "inferred"));
        assert_eq!(k("challenger-teletext"), r(Some("challenger"), Some("teletext-service"), Some(2), "inferred"));
        assert_eq!(k("challenger-microfiche"), r(Some("challenger"), Some("microfiche-reader"), Some(3), "inferred"), "the workspace copy of a card image matches its world");
        assert_eq!(k("challenger-own"), r(Some("challenger"), None, Some(4), "inferred"));
        assert_eq!(k("grounded-2"), r(None, None, Some(5), "inferred"));
        // On register rounds only verdict cards keep a kind.
        let s = seed(Some("bolder"));
        assert_eq!(read(picker_choice(&s, &pg, "assigned", None)), r(None, None, Some(0), "inferred"));
        assert_eq!(read(picker_choice(&s, &pg, "challenger-teletext", None)), r(Some("challenger"), Some("teletext-service"), Some(2), "inferred"));
        // A world two dealt entries share an image with is ambiguous: no id.
        let mut s = seed(None);
        s["dealt"][1]["hero"] = json!("https://cards.test/teletext-service-hero.webp");
        assert_eq!(read(picker_choice(&s, &pg, "challenger-teletext", None)), r(Some("challenger"), None, Some(2), "inferred"));
    }

    #[test]
    fn picker_stays_out_of_non_api_rounds() {
        let pg = explicit_page();
        let mut s = seed(None);
        s["source"] = json!("local");
        assert_eq!(picker_choice(&s, &pg, "a", None), None);
        let mut s = seed(None);
        s["reroll"] = json!(9);
        assert_eq!(picker_choice(&s, &pg, "a", None), None);
    }

    #[test]
    fn seed_references_are_salted_hashes_that_resolve_only_where_recorded() {
        let cwd = temp_dir("reference");
        let l = test_ledger(&cwd);
        let r = l.reference("3f9a1c2e").unwrap();
        assert!(impeccable_common::seed::parse_reference(&r).is_some() && r.len() == 21 && !r.contains("3f9a1c2e"), "{r}");
        assert_eq!(l.reference("3f9a1c2e").unwrap(), r, "stable");
        assert_ne!(Ledger::new(&env(&[("IMPECCABLE_SEED_SALT", "another")]), &cwd).reference("3f9a1c2e").unwrap(), r, "salted");
        // A key resolves to itself; a reference only once this machine recorded its key.
        assert_eq!(l.resolve("k1").unwrap(), "k1");
        assert_eq!(l.resolve(&r), Err(r.clone()));
        l.record_key("3f9a1c2e");
        assert_eq!(l.resolve(&r).unwrap(), "3f9a1c2e");
        // The key record carries no telemetry round.
        assert_eq!(l.round("3f9a1c2e", None), None);
    }

    #[test]
    fn opt_outs_follow_the_env_convention_and_both_configs() {
        let cwd = temp_dir("optout");
        let home = format!("{}/home", cwd);
        let base = |extra: &[(&str, &str)]| {
            let mut e = env(&[("HOME", home.as_str()), ("USERPROFILE", home.as_str())]);
            for (k, v) in extra {
                e.insert(k.to_string(), v.to_string());
            }
            e
        };
        assert_eq!(opt_out_reason(&base(&[]), &cwd), None);
        for v in ["1", "true", "yes", "anything"] {
            assert!(telemetry_disabled(&base(&[("DO_NOT_TRACK", v)]), &cwd), "{v}");
            assert!(telemetry_disabled(&base(&[("IMPECCABLE_NO_TELEMETRY", v)]), &cwd), "{v}");
        }
        for v in ["", "0", "false", "FALSE", " "] {
            assert!(!telemetry_disabled(&base(&[("DO_NOT_TRACK", v)]), &cwd), "{v:?}");
        }
        std::fs::create_dir_all(format!("{}/.impeccable", home)).unwrap();
        std::fs::write(format!("{}/.impeccable/config.json", home), r#"{"telemetry": false}"#).unwrap();
        assert!(opt_out_reason(&base(&[]), &cwd).unwrap().contains("telemetry\": false in"));
        std::fs::write(format!("{}/.impeccable/config.json", home), r#"{"telemetry": true}"#).unwrap();
        assert_eq!(opt_out_reason(&base(&[]), &cwd), None);
        std::fs::create_dir_all(format!("{}/.impeccable", cwd)).unwrap();
        std::fs::write(format!("{}/.impeccable/config.json", cwd), r#"{"telemetry": false}"#).unwrap();
        assert_eq!(opt_out_reason(&base(&[]), &cwd).as_deref(), Some("\"telemetry\": false in .impeccable/config.json"));
    }

    #[test]
    fn the_telemetry_verb_records_the_choice_in_the_user_config() {
        let cwd = temp_dir("verb");
        let home = format!("{}/home", cwd);
        let call = |args: &[&str]| {
            let e = env(&[("HOME", home.as_str()), ("USERPROFILE", home.as_str())]);
            let (mut io, cap) = impeccable_common::Io::captured("", std::path::PathBuf::from(&cwd), e);
            let argv: Vec<String> = args.iter().map(|s| s.to_string()).collect();
            let code = run(&argv, &mut io);
            let out = String::from_utf8(cap.stdout.borrow().clone()).unwrap();
            (code, out)
        };
        assert!(call(&["status"]).1.starts_with("telemetry: on."));
        std::fs::create_dir_all(format!("{}/.impeccable", home)).unwrap();
        std::fs::write(format!("{}/.impeccable/config.json", home), r#"{"other": 1}"#).unwrap();
        let (code, out) = call(&["off"]);
        assert_eq!(code, 0);
        assert!(out.starts_with("telemetry: off (\"telemetry\": false in "), "{out}");
        let cfg: Value = serde_json::from_str(&std::fs::read_to_string(format!("{}/.impeccable/config.json", home)).unwrap()).unwrap();
        assert_eq!(cfg, json!({ "other": 1, "telemetry": false }));
        assert!(call(&["status"]).1.starts_with("telemetry: off"));
        assert!(call(&["on"]).1.starts_with("telemetry: on."));
        let cfg: Value = serde_json::from_str(&std::fs::read_to_string(format!("{}/.impeccable/config.json", home)).unwrap()).unwrap();
        assert_eq!(cfg, json!({ "other": 1 }));
        assert_eq!(call(&["maybe"]).0, 1);
    }

    #[test]
    fn a_project_opt_out_counts_from_a_subdirectory() {
        let root = temp_dir("optout-root");
        std::fs::create_dir_all(format!("{}/.git", root)).unwrap();
        std::fs::create_dir_all(format!("{}/.impeccable", root)).unwrap();
        std::fs::write(format!("{}/.impeccable/config.json", root), r#"{"telemetry": false}"#).unwrap();
        // A workspace monorepo, run from a package: the same roots `context`
        // reads its config defaults from.
        std::fs::write(format!("{}/package.json", root), r#"{"private": true, "workspaces": ["packages/*"]}"#).unwrap();
        let sub = format!("{}/packages/web", root);
        std::fs::create_dir_all(&sub).unwrap();
        std::fs::write(format!("{}/package.json", sub), r#"{"name": "web"}"#).unwrap();
        let e = env(&[("HOME", &format!("{}/home", root)), ("USERPROFILE", &format!("{}/home", root))]);
        let reason = opt_out_reason(&e, &sub).expect("the project root's config counts");
        assert!(reason.contains("\"telemetry\": false in") && reason.contains(".impeccable/config.json"), "{reason}");
    }

    #[test]
    fn telemetry_off_and_on_refuse_to_overwrite_a_malformed_user_config() {
        let cwd = temp_dir("verb-malformed");
        let home = format!("{}/home", cwd);
        std::fs::create_dir_all(format!("{}/.impeccable", home)).unwrap();
        for (body, why) in [("{not json", "is not valid JSON"), ("[1, 2]", "is not a JSON object")] {
            std::fs::write(format!("{}/.impeccable/config.json", home), body).unwrap();
            for cmd in ["off", "on"] {
                let e = env(&[("HOME", home.as_str()), ("USERPROFILE", home.as_str())]);
                let (mut io, cap) = impeccable_common::Io::captured("", std::path::PathBuf::from(&cwd), e);
                assert_eq!(run(&[cmd.to_string()], &mut io), 1);
                let err = String::from_utf8(cap.stderr.borrow().clone()).unwrap();
                assert!(err.contains(why) && err.contains("Nothing was changed"), "{err}");
                assert_eq!(std::fs::read_to_string(format!("{}/.impeccable/config.json", home)).unwrap(), body, "untouched");
            }
        }
    }

    #[test]
    fn references_from_either_salt_resolve() {
        let cwd = temp_dir("two-salts");
        let home = format!("{}/home", cwd);
        let e = env(&[("HOME", home.as_str()), ("USERPROFILE", home.as_str())]);
        // A sandboxed run (no home) makes a project salt and a reference under it.
        // A home that cannot hold a directory (it is a file) stands in for a read-only one.
        let blocked = format!("{}/blocked-home", cwd);
        std::fs::write(&blocked, "").unwrap();
        let sandboxed = Ledger::new(&env(&[("HOME", blocked.as_str()), ("USERPROFILE", blocked.as_str())]), &cwd);
        let old = sandboxed.reference("k1").unwrap();
        sandboxed.record_key("k1");
        // A stray home salt appears later (another tool, a restored backup).
        std::fs::create_dir_all(format!("{}/.impeccable", home)).unwrap();
        std::fs::write(format!("{}/.impeccable/seed-salt", home), "0123456789abcdef0123456789abcdef\n").unwrap();
        let l = Ledger::new(&e, &cwd);
        let new = l.reference("k2").unwrap();
        assert_ne!(impeccable_common::seed::parse_reference(&new), None);
        l.record_key("k2");
        assert_eq!(l.resolve(&old).unwrap(), "k1", "the project salt's reference still resolves");
        assert_eq!(l.resolve(&new).unwrap(), "k2");
    }

    #[cfg(unix)]
    #[test]
    fn a_stale_lock_that_cannot_be_removed_gives_up_within_the_deadline() {
        use std::os::unix::fs::PermissionsExt;
        let dir = std::path::PathBuf::from(temp_dir("lock-stuck"));
        let path = dir.join("ledger.json").to_string_lossy().into_owned();
        let lock_path = format!("{}.lock", path);
        std::fs::write(&lock_path, "").unwrap();
        let old = std::time::SystemTime::now() - Duration::from_secs(60);
        std::fs::File::options().write(true).open(&lock_path).unwrap().set_modified(old).unwrap();
        // A read-only folder: the stale lock can be neither removed nor replaced.
        std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o555)).unwrap();
        if std::fs::remove_file(&lock_path).is_ok() {
            return; // running as root: permissions are not enforced
        }
        let start = std::time::Instant::now();
        assert!(lock(&path).is_none());
        assert!(start.elapsed().as_millis() < LOCK_WAIT_MS + 1_000, "{:?}", start.elapsed());
        let _ = std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o755));
    }
}