car_secrets/

lib.rs

//! Cross-platform secret store for Common Agent Runtime.
//!
//! Unifies OS-native secure storage across the three platforms CAR targets:
//!
//! - **macOS** — `/usr/bin/security` over Keychain Services
//! - **Windows** — Credential Manager (DPAPI)
//! - **Linux** — Secret Service (GNOME Keyring / KWallet / KeePassXC /
//!   anything else that speaks `org.freedesktop.secrets`)
//!
//! The API is intentionally small: `put`, `publish`, `get`, `delete`, `status`,
//! `list`. Callers choose a namespace (`service`) and a key (`account`); values
//! are UTF-8 strings. JSON helpers are provided for structured values.
//!
//! # Availability
//!
//! On headless Linux without a Secret Service daemon, `put`/`get`/`delete`
//! return [`SecretError::Unavailable`]. This is explicit: there is no silent
//! plaintext fallback. Callers should probe [`SecretStore::is_available`]
//! before relying on the store, or handle `Unavailable` with their own fallback.
//!
//! # macOS signing identities and Keychain grants
//!
//! macOS remembers Keychain approval against a caller's code-signing identity
//! and access partition, not against its source tree or executable path. A
//! Developer ID-signed CAR release has the stable team identity `3R69WXRDNY`.
//! A binary produced by `cargo` for local debugging is instead ad-hoc signed:
//! it has no Team ID, and its CDHash serves as a per-build identity that can
//! change whenever it is rebuilt. It therefore does not inherit a release
//! binary's grant, and a grant made to one debug build need not survive the
//! next rebuild. A debug executable that accesses Keychain directly should
//! expect macOS to prompt again; this is the
//! signing boundary working as designed, not evidence that the secret vanished.
//!
//! For prompt-free operator use, run the Developer ID-signed release binary or
//! keep secret-value access behind this crate's stable `/usr/bin/security`
//! helper. Before spawning that helper, CAR uses Security.framework only for a
//! read-only, non-prompting keychain status check; it never accesses an item or
//! changes an ACL through the framework. A supervised agent requests values
//! through its authenticated daemon connection and the local CLI uses that same
//! broker when an owner-only daemon token is available. Tests must set
//! `CAR_SECRETS_FILE_DIR` to an owner-private scratch directory and use that
//! isolated backend; they must not exercise the user's native Keychain from an
//! ad-hoc debug build.
//!
//! Do not try to preserve approval by deleting and recreating a Keychain item.
//! Recreation discards its ACL, partition list, and remembered grants. The
//! macOS backend below consequently routes every operation through the stable
//! Apple-signed `/usr/bin/security` helper, updates existing items in place with
//! `add-generic-password -U`, and performs no automatic post-read ACL repair.
//!
//! # Security boundary
//!
//! Secrets never enter CAR memory, state, or prompt context unless a caller
//! explicitly reads them and passes them into one of those systems. The store
//! treats a missing backend as a hard error so misconfigured environments are
//! loud, not silently insecure.

// The in-process keyring path is every platform except macOS. macOS routes
// secret-value operations — reads, writes, status, and deletes — through
// `/usr/bin/security`, so nothing there opens a keyring `Entry`
// (Parslee-ai/car#897). A read-only Security.framework status call checks that
// the selected keychain is unlocked before any helper process is spawned.
#[cfg(not(target_os = "macos"))]
use keyring::Entry;
use serde::{Deserialize, Serialize};
use thiserror::Error;

pub mod secure_path;
pub use secure_path::{
    atomic_replace_private_file, create_private_file, create_private_file_with_failure_injector,
    ensure_private_dir, ensure_private_dir_with_failure_injector, harden_owner_only,
    harden_owner_only_fallible, harden_private_tree, open_private_append,
    open_private_append_with_failure_injector, open_private_read, open_private_truncate,
    revalidate_private_file, revalidate_private_path, PrivatePathDurabilityFailureInjector,
    PrivatePathDurabilityFailurePoint, PrivateTree, PrivateTreePolicy, PrivateTreeReport,
};

/// Default service (namespace) used when callers don't supply one.
///
/// `"car"` is the per-app namespace shared by every CAR component
/// (`car-cli`, `car-inference` model-key fallback, FFI bindings, WebSocket
/// `secret.*` methods). One shared bucket means `car secrets put OPENAI_API_KEY`
/// stores the same entry that `car-inference` reads at runtime — no namespace
/// translation in users' heads.
///
/// Pre-v0.5.2 this was `"car-runtime"`. The rename was a one-time UX change;
/// any keychain entries written before that date live under the old service
/// name and need to be migrated (or just `car secrets put` again).
pub const DEFAULT_SERVICE: &str = "car";

/// Daemon-owned connection credentials and proof metadata. The raw
/// [`SecretStore`] remains able to lease/delete these entries internally;
/// generic CLI/FFI/RPC wrappers must reject access to the root slots and any
/// platform-derived chunk entries.
pub const OPENROUTER_OAUTH_KEY: &str = "OPENROUTER_OAUTH_API_KEY";
pub const PARSLEE_ACCESS_TOKEN_KEY: &str = "PARSLEE_ACCESS_TOKEN";
pub const PARSLEE_REFRESH_TOKEN_KEY: &str = "PARSLEE_REFRESH_TOKEN";
pub const PARSLEE_EXPIRES_AT_KEY: &str = "PARSLEE_ACCESS_TOKEN_EXPIRES_AT";
pub const PARSLEE_API_BASE_KEY: &str = "PARSLEE_API_BASE";
pub const PARSLEE_ACCOUNTS_KEY: &str = "PARSLEE_ACCOUNTS";
pub const PARSLEE_TOKENS_PREFIX: &str = "PARSLEE_TOKENS_";
pub const PARSLEE_AUTH_GENERATION_KEY: &str = "PARSLEE_AUTH_GENERATION";
pub const PARSLEE_AUTH_COMPLETION_KEY: &str = "PARSLEE_AUTH_COMPLETION";
pub const PARSLEE_ACTIVE_ACCOUNT_ID_KEY: &str = "PARSLEE_ACTIVE_ACCOUNT_ID";
pub const PARSLEE_AUTH_STATE_V2_KEY: &str = "PARSLEE_AUTH_STATE_V2";

/// Process-wide daemon reader used only by supervised-agent env/key resolution.
/// The slot is replaceable so a binding/runtime that already owns an
/// authenticated [`car_daemon_client::proxy::DaemonClient`] can supply that
/// exact connection before its first credential lookup.
fn daemon_secret_reader_slot(
) -> &'static std::sync::RwLock<Option<car_daemon_client::proxy::BlockingDaemonSecretReader>> {
    static READER: std::sync::OnceLock<
        std::sync::RwLock<Option<car_daemon_client::proxy::BlockingDaemonSecretReader>>,
    > = std::sync::OnceLock::new();
    READER.get_or_init(|| std::sync::RwLock::new(None))
}

fn operator_daemon_secret_reader_slot(
) -> &'static std::sync::RwLock<Option<car_daemon_client::proxy::BlockingDaemonSecretReader>> {
    static READER: std::sync::OnceLock<
        std::sync::RwLock<Option<car_daemon_client::proxy::BlockingDaemonSecretReader>>,
    > = std::sync::OnceLock::new();
    READER.get_or_init(|| std::sync::RwLock::new(None))
}

/// Install the daemon connection a supervised runtime already owns as its
/// secret-read broker. This does not connect or read until the first
/// env-keyed credential lookup.
pub fn install_daemon_secret_reader(
    client: std::sync::Arc<car_daemon_client::proxy::DaemonClient>,
) -> Result<(), String> {
    let reader = car_daemon_client::proxy::BlockingDaemonSecretReader::new(client)?;
    *daemon_secret_reader_slot()
        .write()
        .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(reader);
    Ok(())
}

/// Install the local CLI's owner-only host-token connection as its preferred
/// secret reader. Unlike a supervised agent, the operator retains the direct
/// store as an availability fallback when no daemon response arrives.
/// Authorization refusals remain authoritative and never fall through.
pub fn install_operator_daemon_secret_reader(
    client: std::sync::Arc<car_daemon_client::proxy::DaemonClient>,
) -> Result<(), String> {
    if !client.is_local_operator_client() {
        return Err(
            "operator secret broker requires a loopback client authenticated with the owner-only host token"
                .to_string(),
        );
    }
    let reader = car_daemon_client::proxy::BlockingDaemonSecretReader::new(client)?;
    *operator_daemon_secret_reader_slot()
        .write()
        .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(reader);
    Ok(())
}

/// Read through the local CLI's daemon broker when one was installed, falling
/// back to the process's direct store only when the daemon did not answer.
///
/// This is intentionally value-only. Writes and deletes keep their existing
/// direct/coordinated paths, and a daemon refusal cannot be bypassed locally.
pub fn read_via_operator_broker_or_keychain(r: &SecretRef) -> Result<String, SecretError> {
    let reader = operator_daemon_secret_reader_slot()
        .read()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .clone();
    let Some(reader) = reader else {
        return SecretStore::new().get(r);
    };
    match reader.get_for_operator(Some(&r.service), &r.key) {
        Ok(value) => Ok(value),
        Err(car_daemon_client::proxy::SecretBrokerReadError::NotFound { service, key }) => {
            Err(SecretError::NotFound { service, key })
        }
        Err(car_daemon_client::proxy::SecretBrokerReadError::Refused(message)) => {
            Err(SecretError::AccessDenied { message })
        }
        Err(car_daemon_client::proxy::SecretBrokerReadError::Unavailable(error)) => {
            tracing::debug!(error = %error, "local daemon secret broker unavailable; using direct credential store");
            SecretStore::new().get(r)
        }
    }
}

/// Resolve value-free status through the same operator broker decision as a
/// value read. The daemon response is reduced immediately to existence; no
/// caller receives the credential value.
pub fn status_via_operator_broker_or_keychain(r: &SecretRef) -> Result<SecretStatus, SecretError> {
    let reader = operator_daemon_secret_reader_slot()
        .read()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .clone();
    let Some(reader) = reader else {
        return SecretStore::new().status(r);
    };
    match reader.get_for_operator(Some(&r.service), &r.key) {
        Ok(_) => Ok(SecretStatus {
            service: r.service.clone(),
            key: r.key.clone(),
            exists: true,
        }),
        Err(car_daemon_client::proxy::SecretBrokerReadError::NotFound { .. }) => Ok(SecretStatus {
            service: r.service.clone(),
            key: r.key.clone(),
            exists: false,
        }),
        Err(car_daemon_client::proxy::SecretBrokerReadError::Refused(message)) => {
            Err(SecretError::AccessDenied { message })
        }
        Err(car_daemon_client::proxy::SecretBrokerReadError::Unavailable(error)) => {
            tracing::debug!(error = %error, "local daemon secret broker unavailable; using direct credential status");
            SecretStore::new().status(r)
        }
    }
}

fn supervised_agent_credentials_present() -> bool {
    ["CAR_AGENT_ID", "CAR_AGENT_TOKEN"].iter().all(|name| {
        std::env::var(name)
            .ok()
            .is_some_and(|value| !value.trim().is_empty())
    })
}

/// Return the installed daemon reader, or lazily create one for a supervised
/// executable that uses `car-secrets` without constructing an FFI runtime.
fn supervised_daemon_secret_reader(
) -> Result<Option<car_daemon_client::proxy::BlockingDaemonSecretReader>, String> {
    if !supervised_agent_credentials_present() {
        return Ok(None);
    }
    if let Some(reader) = daemon_secret_reader_slot()
        .read()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .clone()
    {
        return Ok(Some(reader));
    }
    let mut slot = daemon_secret_reader_slot()
        .write()
        .unwrap_or_else(|poisoned| poisoned.into_inner());
    if slot.is_none() {
        *slot = Some(car_daemon_client::proxy::BlockingDaemonSecretReader::new(
            car_daemon_client::proxy::DaemonClient::new(),
        )?);
    }
    Ok(slot.clone())
}

fn is_private_chunk_derivative(key: &str, root: &str) -> bool {
    key.strip_prefix(root)
        .is_some_and(|suffix| suffix.starts_with("#chunk"))
}

pub fn is_daemon_private_secret(service: &str, key: &str) -> bool {
    service == DEFAULT_SERVICE
        && (matches!(
            key,
            OPENROUTER_OAUTH_KEY
                | PARSLEE_ACCESS_TOKEN_KEY
                | PARSLEE_REFRESH_TOKEN_KEY
                | PARSLEE_EXPIRES_AT_KEY
                | PARSLEE_API_BASE_KEY
                | PARSLEE_ACCOUNTS_KEY
                | PARSLEE_AUTH_GENERATION_KEY
                | PARSLEE_AUTH_COMPLETION_KEY
                | PARSLEE_ACTIVE_ACCOUNT_ID_KEY
                | PARSLEE_AUTH_STATE_V2_KEY
        ) || key.starts_with(PARSLEE_TOKENS_PREFIX)
            || [
                OPENROUTER_OAUTH_KEY,
                PARSLEE_ACCESS_TOKEN_KEY,
                PARSLEE_REFRESH_TOKEN_KEY,
                PARSLEE_EXPIRES_AT_KEY,
                PARSLEE_API_BASE_KEY,
                PARSLEE_ACCOUNTS_KEY,
                PARSLEE_AUTH_GENERATION_KEY,
                PARSLEE_AUTH_COMPLETION_KEY,
                PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
                PARSLEE_AUTH_STATE_V2_KEY,
            ]
            .iter()
            .any(|root| is_private_chunk_derivative(key, root)))
}

/// Resolve a raw key value for `env_var` from the standard CAR
/// sources, in priority order:
///
/// 1. **Process env var** — `std::env::var(env_var)`. Wins
///    everything (containers, CI, K8s pods, systemd units).
///    `~/.car/env` is loaded into the process env at server
///    startup, so file-based config flows through this path too.
/// 2. **Authenticated daemon broker** — when `CAR_AGENT_ID` and
///    `CAR_AGENT_TOKEN` identify a supervised process. Any broker failure is
///    terminal so the child never opens its own OS credential store.
/// 3. **OS keychain via [`SecretStore`]** — for an unsupervised process, looked
///    up under [`DEFAULT_SERVICE`] = `"car"` with account = `env_var`.
/// 4. **Missing** — returns `None`.
///
/// This read path checks the process environment before constructing the
/// keychain request. On macOS, the direct `get` performs a cheap, non-prompting
/// keychain-status check before spawning `/usr/bin/security`; a locked or
/// unreadable keychain therefore fails without creating a helper process.
/// This read path deliberately does not call [`SecretStore::is_available`].
/// A direct `get` owns its platform's read handling; the resolver does not run
/// a second availability operation that may write and delete a probe item.
///
/// This is the single source of truth for CAR's API-key
/// resolution. Every call site that wants "env first, then
/// keychain" should go through here so the priority can't drift
/// (`car-inference::key_pool`, `car-voice::elevenlabs_*`, and
/// any future remote backend land here, not on their own
/// re-implementation).
pub fn resolve_env_or_keychain(env_var: &str) -> Option<String> {
    if let Ok(v) = std::env::var(env_var) {
        if !v.is_empty() {
            return Some(v);
        }
    }
    let secret_ref = SecretRef::new(DEFAULT_SERVICE, env_var);
    match supervised_daemon_secret_reader() {
        Ok(Some(reader)) => match reader.get(Some(DEFAULT_SERVICE), env_var) {
            Ok(value) if !value.is_empty() => {
                tracing::debug!(env_var = %env_var, "resolved API key through daemon secret broker");
                return Some(value);
            }
            Ok(_) => return None,
            Err(car_daemon_client::proxy::SecretBrokerReadError::NotFound { .. }) => return None,
            Err(car_daemon_client::proxy::SecretBrokerReadError::Refused(error)) => {
                // A daemon response is authoritative. Falling back here would
                // bypass its policy decision and read the same item directly.
                tracing::warn!(env_var = %env_var, error = %error, "daemon secret broker refused credential read");
                return None;
            }
            Err(car_daemon_client::proxy::SecretBrokerReadError::Unavailable(error)) => {
                // A supervised child must never open its own OS credential
                // store. Besides bypassing the one-stable-identity broker, a
                // macOS fallback could spawn a blocking `security` helper.
                tracing::warn!(env_var = %env_var, error = %error, "daemon secret broker unavailable; refusing child-local credential read");
                return None;
            }
        },
        Ok(None) => {}
        Err(error) => {
            tracing::warn!(env_var = %env_var, error = %error, "daemon secret broker could not start; refusing child-local credential read");
            return None;
        }
    }
    match read_via_operator_broker_or_keychain(&secret_ref) {
        Ok(v) if !v.is_empty() => {
            tracing::debug!(env_var = %env_var, "resolved API key from OS keychain");
            Some(v)
        }
        Ok(_) => None, // empty value — treat as missing
        Err(SecretError::NotFound { .. }) => None,
        Err(e) => {
            tracing::warn!(env_var = %env_var, error = %e, "keychain lookup failed");
            None
        }
    }
}

/// Errors the secret store can produce.
#[derive(Debug, Error)]
pub enum SecretError {
    /// No OS backend is available (e.g. headless Linux with no Secret
    /// Service daemon, or a keychain that refused to unlock).
    #[error("secret store unavailable: {0}")]
    Unavailable(String),

    /// The requested entry does not exist.
    #[error("no entry for service={service:?} key={key:?}")]
    NotFound { service: String, key: String },

    /// The OS credential store refused access to an existing item.
    #[error("secret store access denied: {message}")]
    AccessDenied { message: String },

    /// The user dismissed the OS credential prompt without granting access.
    #[error("secret store access cancelled: {message}")]
    UserCancelled { message: String },

    /// A credential helper timed out. Retained for wire/API compatibility;
    /// CAR's macOS security helper no longer owns a timeout or kills its child.
    #[error("secret store helper timed out during {operation}")]
    HelperTimedOut { operation: String },

    /// An OS-native error the store couldn't classify — usually surfaced
    /// verbatim from the underlying keychain API.
    #[error("secret store error: {0}")]
    Backend(String),

    /// A JSON helper was used but the stored value wasn't valid JSON.
    #[error("stored value is not valid JSON: {0}")]
    InvalidJson(String),
}

/// Status of an entry — no value data, safe to log.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SecretStatus {
    pub service: String,
    pub key: String,
    pub exists: bool,
}

/// Result of `SecretStore::availability` — `available` mirrors what
/// `is_available` returns, and `reason` carries the platform-specific
/// detail (e.g. "no Secret Service daemon", "keychain locked") so the
/// FFI surface can report an actionable message instead of a bare
/// boolean.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AvailabilityCheck {
    pub available: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Process-lifetime counts of secret-store operation attempts.
///
/// This is deliberately aggregate-only: it contains no service, key,
/// credential identity, filesystem path, or secret value.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SecretStoreActivity {
    pub get_attempts: u64,
    pub status_attempts: u64,
    pub availability_attempts: u64,
    pub write_attempts: u64,
    pub delete_attempts: u64,
}

static GET_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static STATUS_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static AVAILABILITY_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static WRITE_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
static DELETE_ATTEMPTS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// Snapshot the process-lifetime aggregate secret-store counters.
pub fn secret_store_activity() -> SecretStoreActivity {
    use std::sync::atomic::Ordering;

    SecretStoreActivity {
        get_attempts: GET_ATTEMPTS.load(Ordering::Relaxed),
        status_attempts: STATUS_ATTEMPTS.load(Ordering::Relaxed),
        availability_attempts: AVAILABILITY_ATTEMPTS.load(Ordering::Relaxed),
        write_attempts: WRITE_ATTEMPTS.load(Ordering::Relaxed),
        delete_attempts: DELETE_ATTEMPTS.load(Ordering::Relaxed),
    }
}

/// Logical handle for a secret — (service, key) pair.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct SecretRef {
    pub service: String,
    pub key: String,
}

impl SecretRef {
    pub fn new(service: impl Into<String>, key: impl Into<String>) -> Self {
        Self {
            service: service.into(),
            key: key.into(),
        }
    }

    pub fn with_default_service(key: impl Into<String>) -> Self {
        Self {
            service: DEFAULT_SERVICE.to_string(),
            key: key.into(),
        }
    }
}

/// Cross-platform secret store backed by the host OS keychain.
///
/// Stateless by design — it holds no cached secrets. Every call round-trips
/// to the OS. That makes concurrent usage safe and avoids any in-process
/// leak surface beyond the immediate call's return value.
#[derive(Debug, Default, Clone, Copy)]
pub struct SecretStore;

impl SecretStore {
    pub fn new() -> Self {
        Self
    }

    /// Store a UTF-8 secret under `(service, key)`. Replaces any existing
    /// value at the same ref.
    ///
    /// On macOS, writes via `/usr/bin/security add-generic-password -U -A`.
    /// Every CAR read, write, status check, and delete uses that same stable
    /// Apple-signed helper identity instead of a release- or rebuild-specific
    /// CAR binary identity. `-U` updates existing items in place, preserving
    /// their ACL, partition list, and user-approved grants; `-A` applies when a
    /// new item is created (car-0o9).
    ///
    /// Trade-off: the value transits argv during the spawn (visible to
    /// `ps` from the same user for ~milliseconds). Acceptable for the
    /// "single-user developer machine" threat model; any process that
    /// can see argv on this machine can also read the keychain
    /// directly via `security`. On other platforms, behavior is
    /// unchanged (keyring crate's native backend).
    pub fn put(&self, r: &SecretRef, value: &str) -> Result<(), SecretError> {
        WRITE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_put(self, r, value)
    }

    /// Publish one authoritative value without exposing a partially-published
    /// replacement to readers.
    ///
    /// This is deliberately separate from [`Self::put`]. Parslee auth stores
    /// its entire active credential transaction in one JSON record and uses
    /// this method as the commit point. macOS updates the existing Keychain item
    /// in place (no pre-delete gap), the debug file backend renames an
    /// owner-private staging file, and Windows stages a revision-tagged
    /// inactive chunk generation before committing the root sentinel last.
    /// Windows retains the prior generation for concurrent readers and uses
    /// deterministic A/B slots plus high-water manifests so crashes cannot
    /// grow Credential Manager entry cardinality without bound.
    ///
    /// Multiple publishers for the same ref must be serialized by the caller.
    /// Parslee auth does this with its coordinator lock; readers may run
    /// concurrently with a publisher.
    pub fn publish(&self, r: &SecretRef, value: &str) -> Result<(), SecretError> {
        WRITE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_publish(self, r, value)
    }

    /// Store a structured value serialized as JSON.
    pub fn put_json<T: Serialize>(&self, r: &SecretRef, value: &T) -> Result<(), SecretError> {
        let s = serde_json::to_string(value)
            .map_err(|e| SecretError::Backend(format!("serialize: {}", e)))?;
        self.put(r, &s)
    }

    /// Read a UTF-8 secret. Returns `NotFound` if no entry exists.
    ///
    /// On macOS, reads through `/usr/bin/security` first so repeated
    /// helper rebuilds do not churn Keychain prompts against each
    /// binary's CDHash. Backend/authorization failures are returned
    /// directly instead of falling back to an in-process read path that
    /// can trigger a second prompt.
    pub fn get(&self, r: &SecretRef) -> Result<String, SecretError> {
        GET_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_get(self, r)
    }

    /// Read a structured value previously stored via `put_json`.
    pub fn get_json<T: for<'de> Deserialize<'de>>(&self, r: &SecretRef) -> Result<T, SecretError> {
        let raw = self.get(r)?;
        serde_json::from_str(&raw).map_err(|e| SecretError::InvalidJson(e.to_string()))
    }

    /// Delete an entry. Returns Ok even if the entry didn't exist — idempotent
    /// from the caller's perspective.
    ///
    /// On macOS, deletes through `/usr/bin/security` first so the
    /// Apple-signed helper, not the rebuilt caller binary, owns
    /// Keychain authorization.
    pub fn delete(&self, r: &SecretRef) -> Result<(), SecretError> {
        DELETE_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_delete(self, r)
    }

    /// Existence check without returning the value. Safe to log.
    ///
    /// On macOS, checks status through `/usr/bin/security` first for
    /// the same CDHash-stable authorization behavior as `get`.
    pub fn status(&self, r: &SecretRef) -> Result<SecretStatus, SecretError> {
        STATUS_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        platform_status(self, r)
    }

    /// Reserved internal service name used for availability probing.
    /// Consumers must not write user secrets under this service.
    const PROBE_SERVICE: &'static str = "car-internal";
    const PROBE_KEY: &'static str = "__availability_probe__";
    #[cfg(target_os = "macos")]
    const PROBE_VALUE: &'static str = "car-availability-probe";

    /// Probe whether the OS secret store can persist credentials.
    ///
    /// Platform/backend failures mean the store is unavailable; the detailed
    /// form preserves their reason.
    ///
    /// # Side effects
    ///
    /// - On macOS the non-prompting Security.framework preflight rejects a
    ///   locked or unreadable keychain before any helper starts. Availability
    ///   then requires `/usr/bin/security` to read the reserved item and write
    ///   or update its fixed, non-secret value. The sentinel is retained rather
    ///   than deleted, so probing never creates a delete gap.
    /// - Other platforms probe their native keyring backend with the reserved
    ///   sentinel.
    /// - Performance: macOS performs one read and one write; other platforms
    ///   perform one backend round-trip. Not cached.
    pub fn is_available(&self) -> bool {
        self.availability().available
    }

    /// Detailed availability probe. Same platform probe as `is_available`,
    /// but distinguishes "no backend at all" from a specific platform
    /// failure so the FFI surface can emit a `reason` matching the
    /// pattern used by the other v0.4 capability probes
    /// (`accountsList`, `calendarList`, etc.).
    pub fn availability(&self) -> AvailabilityCheck {
        AVAILABILITY_ATTEMPTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        // Reason is only populated when `available == false`. Reachable
        // backends never carry a reason — callers can rely on
        // `available && reason.is_none()` for happy-path branching.
        // The opt-in file backend (test/headless redirect) is always
        // "available" — it is just the local filesystem.
        if file_backend_dir().is_some() {
            return AvailabilityCheck {
                available: true,
                reason: None,
            };
        }
        platform_availability(self)
    }

    /// Not compiled on macOS — and that gate is the regression barrier here,
    /// not a test. Every macOS secret-value operation goes through
    /// `/usr/bin/security`, so re-routing one of them back through the in-process keyring path would
    /// reach for `self.entry` and fail to compile. Worth stating because a
    /// test cannot cover it: the tests below inject a fake `SecurityCli`, so
    /// they exercise the helper and say nothing about which body
    /// `platform_availability` dispatches to.
    ///
    /// `keyring` is also a target-specific non-macOS dependency, so even a
    /// fully-qualified framework call fails to compile on macOS. This makes the
    /// one-writer-identity rule structural rather than conventional (car-0o9).
    #[cfg(not(target_os = "macos"))]
    fn entry(&self, r: &SecretRef) -> Result<Entry, SecretError> {
        Entry::new(&r.service, &r.key).map_err(|e| classify(e, "entry"))
    }
}

// ---------------------------------------------------------------------------
// Platform-dispatched keychain operations.
//
// macOS: shell out to `/usr/bin/security` for reads, writes, status checks,
// deletes, and the availability probe. The Apple-signed helper keeps Keychain
// authorization stable across rebuilt CAR binaries whose CDHash changes.
// Writes update existing items in place so saved grants and partition lists
// survive; new items use `-A` through the same stable helper identity.
//
// Other platforms: pass through to keyring (its native backends behave
// correctly).
// ---------------------------------------------------------------------------

/// Test/headless redirect: when `CAR_SECRETS_FILE_DIR` names a directory, the
/// store is backed by plaintext files there instead of the OS keychain. This is
/// the SAME env-keyed-redirect idiom as `resolve_env_or_keychain`'s
/// process-env precedence — a no-op in production (the daemon never sets this
/// var), but it lets tests drive the real `put`/`get`/`delete` code path WITHOUT
/// the macOS keychain's interactive-authorization prompt (which cancels
/// unattended, `code=154`). Each secret lands at `<dir>/<service>.<key>`.
///
/// SECURITY: plaintext on disk — acceptable ONLY because this is opt-in via an
/// env var production never sets. The keychain remains the sole production
/// backing store.
///
/// Two hard guards make a production leak structurally impossible:
///
/// 1. **Release builds refuse it entirely.** The redirect is honored ONLY under
///    `cfg!(debug_assertions)` (debug/test builds). A RELEASE binary — which is
///    what production ships — returns `None` even when the env var is set, so a
///    stray `CAR_SECRETS_FILE_DIR` can never route real secrets to plaintext in
///    prod.
/// 2. **First engagement warns loudly.** The first time the redirect is honored
///    in a process, a one-time `tracing::warn!` fires so a misconfigured dev /
///    CI run is visible, not silent.
fn file_backend_dir() -> Option<std::path::PathBuf> {
    // Release builds (production) NEVER honor the redirect — secrets always go
    // to the OS keychain. The env var is a debug/test-only seam.
    if !cfg!(debug_assertions) {
        return None;
    }
    match std::env::var_os("CAR_SECRETS_FILE_DIR") {
        Some(d) if !d.is_empty() => {
            // One-time loud warning the first time the plaintext file backend
            // engages in this process.
            static WARNED: std::sync::Once = std::sync::Once::new();
            WARNED.call_once(|| {
                tracing::warn!(
                    "CAR_SECRETS_FILE_DIR set — secrets are PLAINTEXT ON DISK; \
                     test-only, never production"
                );
            });
            Some(std::path::PathBuf::from(d))
        }
        _ => None,
    }
}

fn file_backend_path(dir: &std::path::Path, r: &SecretRef) -> std::path::PathBuf {
    // Sanitize path separators so a service/key never escapes the dir.
    let sanitize = |s: &str| s.replace(['/', '\\', '.'], "_");
    dir.join(format!("{}.{}", sanitize(&r.service), sanitize(&r.key)))
}

fn file_backend_put(dir: &std::path::Path, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    std::fs::create_dir_all(dir)
        .map_err(|e| SecretError::Backend(format!("file backend mkdir: {e}")))?;
    std::fs::write(file_backend_path(dir, r), value)
        .map_err(|e| SecretError::Backend(format!("file backend write: {e}")))
}

fn file_backend_publish(
    dir: &std::path::Path,
    r: &SecretRef,
    value: &str,
) -> Result<(), SecretError> {
    use std::io::Write;

    std::fs::create_dir_all(dir)
        .map_err(|e| SecretError::Backend(format!("file backend mkdir: {e}")))?;
    let destination = file_backend_path(dir, r);
    let nonce = publication_nonce();
    let staging = destination.with_extension(format!("stage-{nonce}"));
    let mut options = std::fs::OpenOptions::new();
    options.create_new(true).write(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        options.mode(0o600);
    }
    let mut file = options
        .open(&staging)
        .map_err(|e| SecretError::Backend(format!("file backend stage: {e}")))?;
    file.write_all(value.as_bytes())
        .and_then(|_| file.sync_all())
        .map_err(|e| SecretError::Backend(format!("file backend stage write: {e}")))?;
    drop(file);
    if let Err(error) = std::fs::rename(&staging, &destination) {
        let _ = std::fs::remove_file(&staging);
        return Err(SecretError::Backend(format!(
            "file backend publish rename: {error}"
        )));
    }
    Ok(())
}

/// Whether a `NotFound` from an operation under `dir` means "this entry is
/// absent" rather than "this store is unusable".
///
/// The two are the same errno on one platform and not on the other. With a
/// REGULAR FILE configured where the secrets directory should be, opening an
/// entry under it fails with `ENOTDIR` on unix — which is not `NotFound`, so it
/// surfaced as a backend error — but with `ERROR_PATH_NOT_FOUND` on Windows,
/// which Rust maps straight to `io::ErrorKind::NotFound`. The store then
/// answered "that secret does not exist" for a store it could not read at all.
///
/// The consequence was not cosmetic. `car_auth`'s credential resolution treats
/// `NotFound` as "no V2 record yet" and runs a legacy-migration sweep — five
/// further reads of the same broken store — instead of failing on the first one
/// and entering keychain cooldown (Parslee-ai/car#1014). `delete` reported
/// success on a store it never touched, and `status` reported `exists: false`
/// rather than admitting it could not tell.
///
/// The discriminator is whether the configured path is something OTHER than a
/// directory, and it is the same question on every platform.
///
/// Note the second arm: a directory that does not exist YET is not a broken
/// store. Only `put`/`publish` call `create_dir_all`, so on a first run — before
/// anything has been written — the path is legitimately absent, and a `get`
/// there means "no secret yet", exactly as it always has. Treating that as a
/// backend error would send `car_auth` into keychain cooldown on a fresh
/// install instead of reporting "not signed in".
fn file_backend_entry_is_merely_absent(dir: &std::path::Path) -> bool {
    match std::fs::metadata(dir) {
        Ok(metadata) => metadata.is_dir(),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            // A genuinely absent directory is a normal first run, but Windows
            // also reports NotFound when an ancestor is a regular file. Walk to
            // the nearest existing ancestor and require it to be a directory;
            // any other metadata error means "could not inspect", not "absent".
            for ancestor in dir.ancestors().skip(1) {
                match std::fs::metadata(ancestor) {
                    Ok(metadata) => return metadata.is_dir(),
                    Err(ancestor_error)
                        if ancestor_error.kind() == std::io::ErrorKind::NotFound => {}
                    Err(_) => return false,
                }
            }
            false
        }
        Err(_) => false,
    }
}

fn file_backend_get(dir: &std::path::Path, r: &SecretRef) -> Result<String, SecretError> {
    match std::fs::read_to_string(file_backend_path(dir, r)) {
        Ok(v) => Ok(v),
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && file_backend_entry_is_merely_absent(dir) =>
        {
            Err(SecretError::NotFound {
                service: r.service.clone(),
                key: r.key.clone(),
            })
        }
        Err(e) => Err(SecretError::Backend(format!("file backend read: {e}"))),
    }
}

fn file_backend_delete(dir: &std::path::Path, r: &SecretRef) -> Result<(), SecretError> {
    match std::fs::remove_file(file_backend_path(dir, r)) {
        Ok(()) => Ok(()),
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && file_backend_entry_is_merely_absent(dir) =>
        {
            Ok(())
        }
        Err(e) => Err(SecretError::Backend(format!("file backend delete: {e}"))),
    }
}

fn file_backend_status(dir: &std::path::Path, r: &SecretRef) -> SecretStatus {
    SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        // `SecretStatus` has no error/unknown state. Keep the historical false
        // answer for both an absent entry and an unusable debug store; get/delete
        // carry the richer error distinction above.
        exists: file_backend_path(dir, r).exists(),
    }
}

#[cfg(target_os = "macos")]
fn platform_put(_store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_put(&dir, r, value);
    }
    mac_put_via_security_cli(&r.service, &r.key, value)
}

#[cfg(target_os = "macos")]
fn platform_publish(_store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    mac_publish_via_security_cli(&r.service, &r.key, value)
}

// --- Windows Credential Manager large-secret chunking ---------------------
//
// A single Windows credential's blob is capped well below the length of a
// Parslee JWT access token — writing one fails with `set_password ... longer
// than platform limit of 2560 chars`. macOS Keychain and Linux Secret Service
// have no such tight limit, so this never surfaced until CAR was exercised on
// real Windows hardware. The workaround, standard for this platform limit, is
// to split an oversized secret across N chunk entries and leave a sentinel
// under the real key that records the chunk count. Reads reassemble
// transparently, so every reader (car-auth, car-inference via car-auth) is
// unaffected. Backward compatible: a value stored as a single entry (no
// sentinel) is returned verbatim, and only Windows takes this path.

/// Sentinel written under the real key when a secret was chunked. The trailing
/// number is the chunk count. Distinctive enough that no real token/API key
/// collides with it.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_SENTINEL: &str = "__car_secrets_chunked_v1__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_SENTINEL_V2: &str = "__car_secrets_chunked_v2__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_SENTINEL_V3: &str = "__car_secrets_chunked_v3__:";
#[cfg(any(target_os = "windows", test))]
const CHUNK_VALUE_V3: &str = "__car_secrets_chunk_v3__:";
/// UTF-16 length above which we chunk. Comfortably under the ~2560 platform cap
/// with headroom for the credential's other attributes.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_THRESHOLD_UTF16: usize = 2000;
/// Characters per chunk. 1000 chars ≤ 2000 UTF-16 units even for all-BMP text.
#[cfg(any(not(target_os = "macos"), test))]
const CHUNK_CHARS: usize = 1000;
/// Hard ceiling for deterministic Windows chunk slots. Publication cardinality
/// is therefore bounded at two generations of at most this many chunks, even
/// when a process repeatedly crashes before swapping the root credential.
#[cfg(any(target_os = "windows", test))]
const WINDOWS_MAX_CHUNKS: usize = 1024;
#[cfg(any(target_os = "windows", test))]
const WINDOWS_READ_ATTEMPTS: usize = 4;

/// Derived ref for chunk `i` of a chunked secret.
#[cfg(not(target_os = "macos"))]
fn chunk_ref(r: &SecretRef, i: usize) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunk{}", r.key, i))
}

#[cfg(target_os = "windows")]
fn chunk_v2_ref(r: &SecretRef, nonce: &str, i: usize) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunkv2#{nonce}#{i}", r.key))
}

#[cfg(target_os = "windows")]
fn chunk_v3_ref(r: &SecretRef, generation: ChunkGeneration, i: usize) -> SecretRef {
    SecretRef::new(
        r.service.clone(),
        format!("{}#chunkv3#{}#{i}", r.key, generation.label()),
    )
}

#[cfg(target_os = "windows")]
fn chunk_v3_manifest_ref(r: &SecretRef, generation: ChunkGeneration) -> SecretRef {
    SecretRef::new(
        r.service.clone(),
        format!("{}#chunkv3#{}#manifest", r.key, generation.label()),
    )
}

#[cfg(target_os = "windows")]
fn chunk_v3_retired_v2_ref(r: &SecretRef) -> SecretRef {
    SecretRef::new(r.service.clone(), format!("{}#chunkv3#retired-v2", r.key))
}

/// Split a string into pieces of at most `n` chars, on char boundaries.
#[cfg(any(not(target_os = "macos"), test))]
fn split_on_chars(s: &str, n: usize) -> Vec<String> {
    let mut out = Vec::new();
    let mut cur = String::new();
    let mut count = 0usize;
    for ch in s.chars() {
        cur.push(ch);
        count += 1;
        if count == n {
            out.push(std::mem::take(&mut cur));
            count = 0;
        }
    }
    if !cur.is_empty() {
        out.push(cur);
    }
    out
}

fn publication_nonce() -> String {
    static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let sequence = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|duration| duration.as_nanos())
        .unwrap_or_default();
    format!("{:x}-{:x}-{:x}", std::process::id(), nanos, sequence)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
#[cfg(any(target_os = "windows", test))]
enum ChunkGeneration {
    A,
    B,
}

#[cfg(any(target_os = "windows", test))]
impl ChunkGeneration {
    fn label(self) -> &'static str {
        match self {
            Self::A => "a",
            Self::B => "b",
        }
    }

    fn inactive(self) -> Self {
        match self {
            Self::A => Self::B,
            Self::B => Self::A,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
struct ChunkPublicationPlan {
    generation: ChunkGeneration,
    revision: String,
    chunks: Vec<String>,
    root: String,
}

#[cfg(any(target_os = "windows", test))]
fn chunk_publication_plan(
    value: &str,
    generation: ChunkGeneration,
    revision: &str,
) -> Result<ChunkPublicationPlan, SecretError> {
    if revision.is_empty() || revision.contains(':') {
        return Err(SecretError::Backend(
            "invalid Windows credential publication revision".to_string(),
        ));
    }
    let mut chunks = split_on_chars(value, CHUNK_CHARS);
    if chunks.is_empty() {
        chunks.push(String::new());
    }
    if chunks.len() > WINDOWS_MAX_CHUNKS {
        return Err(SecretError::Backend(format!(
            "Windows credential publication requires {} chunks; maximum is {WINDOWS_MAX_CHUNKS}",
            chunks.len()
        )));
    }
    Ok(ChunkPublicationPlan {
        generation,
        revision: revision.to_string(),
        root: format!(
            "{CHUNK_SENTINEL_V3}{}:{revision}:{}",
            generation.label(),
            chunks.len()
        ),
        chunks,
    })
}

#[cfg(any(target_os = "windows", test))]
fn encode_v3_chunk(revision: &str, value: &str) -> String {
    format!("{CHUNK_VALUE_V3}{revision}:{value}")
}

#[cfg(any(target_os = "windows", test))]
fn decode_v3_chunk<'a>(raw: &'a str, revision: &str) -> Result<&'a str, SecretError> {
    let payload = raw.strip_prefix(CHUNK_VALUE_V3).ok_or_else(|| {
        SecretError::Backend("invalid Windows v3 credential chunk metadata".to_string())
    })?;
    let (stored_revision, value) = payload.split_once(':').ok_or_else(|| {
        SecretError::Backend("invalid Windows v3 credential chunk metadata".to_string())
    })?;
    if stored_revision != revision {
        return Err(SecretError::Backend(
            "Windows credential chunk revision changed during read".to_string(),
        ));
    }
    Ok(value)
}

#[cfg(any(target_os = "windows", test))]
fn parse_v2_sentinel(raw: &str) -> Option<(&str, usize)> {
    let payload = raw.strip_prefix(CHUNK_SENTINEL_V2)?;
    let (nonce, count) = payload.rsplit_once(':')?;
    let count = count.parse::<usize>().ok()?;
    if nonce.is_empty() || count == 0 || count > WINDOWS_MAX_CHUNKS {
        return None;
    }
    Some((nonce, count))
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
enum WindowsRootLayout {
    Inline,
    LegacyV1 {
        count: usize,
    },
    LegacyV2 {
        nonce: String,
        count: usize,
    },
    V3 {
        generation: ChunkGeneration,
        revision: String,
        count: usize,
    },
}

#[cfg(any(target_os = "windows", test))]
fn windows_root_layout(raw: &str) -> Result<WindowsRootLayout, SecretError> {
    if let Some(payload) = raw.strip_prefix(CHUNK_SENTINEL_V3) {
        let (publication, count) = payload.rsplit_once(':').ok_or_else(|| {
            SecretError::Backend("invalid Windows v3 credential root metadata".to_string())
        })?;
        let (generation, revision) = publication.split_once(':').ok_or_else(|| {
            SecretError::Backend("invalid Windows v3 credential root metadata".to_string())
        })?;
        let generation = match generation {
            "a" => ChunkGeneration::A,
            "b" => ChunkGeneration::B,
            _ => {
                return Err(SecretError::Backend(
                    "invalid Windows v3 credential generation".to_string(),
                ))
            }
        };
        if revision.is_empty() {
            return Err(SecretError::Backend(
                "invalid Windows v3 credential publication revision".to_string(),
            ));
        }
        let count = count
            .parse::<usize>()
            .ok()
            .filter(|count| *count > 0 && *count <= WINDOWS_MAX_CHUNKS);
        return count
            .map(|count| WindowsRootLayout::V3 {
                generation,
                revision: revision.to_string(),
                count,
            })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v3 credential chunk count".to_string())
            });
    }

    if raw.starts_with(CHUNK_SENTINEL_V2) {
        return parse_v2_sentinel(raw)
            .map(|(nonce, count)| WindowsRootLayout::LegacyV2 {
                nonce: nonce.to_string(),
                count,
            })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v2 credential root metadata".to_string())
            });
    }

    if let Some(count) = raw.strip_prefix(CHUNK_SENTINEL) {
        return count
            .parse::<usize>()
            .ok()
            .filter(|count| *count > 0 && *count <= WINDOWS_MAX_CHUNKS)
            .map(|count| WindowsRootLayout::LegacyV1 { count })
            .ok_or_else(|| {
                SecretError::Backend("invalid Windows v1 credential chunk count".to_string())
            });
    }

    Ok(WindowsRootLayout::Inline)
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
#[cfg(any(target_os = "windows", test))]
enum WindowsCredentialSlot {
    Root,
    LegacyV1Chunk(usize),
    LegacyV2Chunk {
        nonce: String,
        index: usize,
    },
    V3Chunk {
        generation: ChunkGeneration,
        index: usize,
    },
    V3Manifest(ChunkGeneration),
    RetiredV2Manifest,
}

#[cfg(any(target_os = "windows", test))]
trait WindowsCredentialBackend {
    fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError>;
    fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError>;
    fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError>;
}

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
#[cfg(any(target_os = "windows", test))]
struct WindowsCleanupReport {
    failures: usize,
}

#[cfg(any(target_os = "windows", test))]
fn cleanup_windows_slot(
    backend: &mut impl WindowsCredentialBackend,
    slot: WindowsCredentialSlot,
    report: &mut WindowsCleanupReport,
) {
    if backend.delete(&slot).is_err() {
        report.failures += 1;
    }
}

#[cfg(any(target_os = "windows", test))]
fn read_generation_manifest(
    backend: &mut impl WindowsCredentialBackend,
    generation: ChunkGeneration,
) -> Result<usize, SecretError> {
    let Some(raw) = backend.read(&WindowsCredentialSlot::V3Manifest(generation))? else {
        return Ok(0);
    };
    raw.parse::<usize>()
        .ok()
        .filter(|count| *count <= WINDOWS_MAX_CHUNKS)
        .ok_or_else(|| {
            SecretError::Backend("invalid Windows credential generation manifest".to_string())
        })
}

#[cfg(any(target_os = "windows", test))]
fn read_retired_v2_manifest(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<Option<(String, usize)>, SecretError> {
    let Some(raw) = backend.read(&WindowsCredentialSlot::RetiredV2Manifest)? else {
        return Ok(None);
    };
    match windows_root_layout(&raw)? {
        WindowsRootLayout::LegacyV2 { nonce, count } => Ok(Some((nonce, count))),
        _ => Err(SecretError::Backend(
            "invalid retired Windows v2 credential manifest".to_string(),
        )),
    }
}

#[cfg(any(target_os = "windows", test))]
fn cleanup_retired_v2(
    backend: &mut impl WindowsCredentialBackend,
    nonce: &str,
    count: usize,
    report: &mut WindowsCleanupReport,
) {
    let failures_before = report.failures;
    for index in 0..count {
        cleanup_windows_slot(
            backend,
            WindowsCredentialSlot::LegacyV2Chunk {
                nonce: nonce.to_string(),
                index,
            },
            report,
        );
    }
    // Keep the deterministic manifest when any chunk cleanup failed so the
    // next publication/delete can resume the sweep without guessing a nonce.
    if report.failures == failures_before {
        cleanup_windows_slot(backend, WindowsCredentialSlot::RetiredV2Manifest, report);
    }
}

#[cfg(any(target_os = "windows", test))]
fn publish_windows_value(
    backend: &mut impl WindowsCredentialBackend,
    value: &str,
) -> Result<WindowsCleanupReport, SecretError> {
    let previous_root = backend.read(&WindowsCredentialSlot::Root)?;
    let previous_layout = previous_root
        .as_deref()
        .map(windows_root_layout)
        .transpose()?;
    let retired_v2_before = read_retired_v2_manifest(backend)?;
    let newly_retired_v2 = match previous_layout.as_ref() {
        Some(WindowsRootLayout::LegacyV2 { nonce, count }) => {
            let root = previous_root
                .as_deref()
                .expect("a parsed legacy root came from a present credential");
            backend.write(&WindowsCredentialSlot::RetiredV2Manifest, root)?;
            Some((nonce.clone(), *count))
        }
        _ => None,
    };
    let generation = match previous_layout {
        Some(WindowsRootLayout::V3 { generation, .. }) => generation.inactive(),
        _ => ChunkGeneration::A,
    };
    let plan = chunk_publication_plan(value, generation, &publication_nonce())?;

    // This non-secret high-water mark is persisted before any chunk mutation.
    // If the process dies while staging, the next writer knows exactly how far
    // it must sweep. Repeated crashes overwrite the same bounded slot set.
    let previous_bound = read_generation_manifest(backend, generation)?;
    let high_water = previous_bound.max(plan.chunks.len());
    backend.write(
        &WindowsCredentialSlot::V3Manifest(generation),
        &high_water.to_string(),
    )?;

    let mut staged = 0;
    for (index, chunk) in plan.chunks.iter().enumerate() {
        let slot = WindowsCredentialSlot::V3Chunk { generation, index };
        if let Err(error) = backend.write(&slot, &encode_v3_chunk(&plan.revision, chunk)) {
            let mut ignored_cleanup = WindowsCleanupReport::default();
            for staged_index in 0..staged {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::V3Chunk {
                        generation,
                        index: staged_index,
                    },
                    &mut ignored_cleanup,
                );
            }
            return Err(error);
        }
        staged += 1;
    }

    // The root write is the sole commit point. The previous active generation
    // is deliberately retained so a reader that captured its root can finish.
    if let Err(error) = backend.write(&WindowsCredentialSlot::Root, &plan.root) {
        let mut ignored_cleanup = WindowsCleanupReport::default();
        for staged_index in 0..staged {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Chunk {
                    generation,
                    index: staged_index,
                },
                &mut ignored_cleanup,
            );
        }
        return Err(error);
    }

    let mut cleanup = WindowsCleanupReport::default();
    let tail_failures_before = cleanup.failures;
    for index in plan.chunks.len()..high_water {
        cleanup_windows_slot(
            backend,
            WindowsCredentialSlot::V3Chunk { generation, index },
            &mut cleanup,
        );
    }
    if cleanup.failures == tail_failures_before
        && backend
            .write(
                &WindowsCredentialSlot::V3Manifest(generation),
                &plan.chunks.len().to_string(),
            )
            .is_err()
    {
        cleanup.failures += 1;
    }

    // A v2 generation retired by this commit survives at least one full v3
    // publication. That lets a reader which captured the old nonce finish.
    // A later commit reclaims it through the deterministic manifest; failures
    // leave the manifest in place for the next recovery sweep.
    if let Some((nonce, count)) = retired_v2_before {
        if newly_retired_v2.as_ref() != Some(&(nonce.clone(), count)) {
            cleanup_retired_v2(backend, &nonce, count, &mut cleanup);
        }
    }

    Ok(cleanup)
}

/// Best-effort delete of any chunk entries `#chunk0..` for `r`, stopping at the
/// first that doesn't exist. Used before a rewrite and on delete so stale
/// chunks from a previous large value never linger.
#[cfg(not(target_os = "macos"))]
fn clear_chunks(store: &SecretStore, r: &SecretRef) {
    for i in 0..1024 {
        let cr = chunk_ref(r, i);
        let Ok(entry) = store.entry(&cr) else { break };
        match entry.delete_credential() {
            Ok(_) => {}
            Err(keyring::Error::NoEntry) => break,
            Err(_) => break,
        }
    }
}

#[cfg(any(target_os = "windows", test))]
fn read_windows_value(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<Option<String>, SecretError> {
    for attempt in 0..WINDOWS_READ_ATTEMPTS {
        let Some(root) = backend.read(&WindowsCredentialSlot::Root)? else {
            return Ok(None);
        };
        let (slots, expected_revision) = match windows_root_layout(&root)? {
            WindowsRootLayout::Inline => return Ok(Some(root)),
            WindowsRootLayout::LegacyV1 { count } => (
                (0..count)
                    .map(WindowsCredentialSlot::LegacyV1Chunk)
                    .collect::<Vec<_>>(),
                None,
            ),
            WindowsRootLayout::LegacyV2 { nonce, count } => (
                (0..count)
                    .map(|index| WindowsCredentialSlot::LegacyV2Chunk {
                        nonce: nonce.clone(),
                        index,
                    })
                    .collect::<Vec<_>>(),
                None,
            ),
            WindowsRootLayout::V3 {
                generation,
                revision,
                count,
            } => (
                (0..count)
                    .map(|index| WindowsCredentialSlot::V3Chunk { generation, index })
                    .collect::<Vec<_>>(),
                Some(revision),
            ),
        };

        let mut value = String::new();
        let mut chunk_error = None;
        for slot in slots {
            match backend.read(&slot) {
                Ok(Some(chunk)) => {
                    if let Some(revision) = expected_revision.as_deref() {
                        match decode_v3_chunk(&chunk, revision) {
                            Ok(chunk) => value.push_str(chunk),
                            Err(error) => {
                                chunk_error = Some(error);
                                break;
                            }
                        }
                    } else {
                        value.push_str(&chunk);
                    }
                }
                Ok(None) => {
                    chunk_error = Some(SecretError::Backend(
                        "Windows credential publication is incomplete".to_string(),
                    ));
                    break;
                }
                Err(error) => {
                    chunk_error = Some(error);
                    break;
                }
            }
        }

        let root_after = backend.read(&WindowsCredentialSlot::Root);
        if matches!(&root_after, Ok(Some(current)) if current != &root) {
            if chunk_error.is_none() {
                // Every chunk carried the captured revision (or was a retained
                // legacy generation), so this complete old value is safe.
                return Ok(Some(value));
            }
            if attempt + 1 < WINDOWS_READ_ATTEMPTS {
                continue;
            }
            return Err(SecretError::Backend(
                "Windows credential root changed during every read attempt".to_string(),
            ));
        }
        if let Some(error) = chunk_error {
            return Err(error);
        }
        match root_after {
            Ok(Some(current)) if current == root => return Ok(Some(value)),
            Ok(_) if attempt + 1 < WINDOWS_READ_ATTEMPTS => continue,
            Ok(_) => {
                return Err(SecretError::Backend(
                    "Windows credential root changed during every read attempt".to_string(),
                ))
            }
            Err(error) => return Err(error),
        }
    }
    Err(SecretError::Backend(
        "Windows credential read retry limit reached".to_string(),
    ))
}

#[cfg(any(target_os = "windows", test))]
fn delete_windows_value(
    backend: &mut impl WindowsCredentialBackend,
) -> Result<WindowsCleanupReport, SecretError> {
    let root = backend.read(&WindowsCredentialSlot::Root)?;
    let layout = root.as_deref().map(windows_root_layout).transpose()?;
    let retired_v2 = read_retired_v2_manifest(backend)?;

    // Resolve every cleanup bound before deleting the root. A metadata/backend
    // error therefore leaves the only authoritative generation untouched.
    let mut generation_bounds = [
        (
            ChunkGeneration::A,
            read_generation_manifest(backend, ChunkGeneration::A)?,
        ),
        (
            ChunkGeneration::B,
            read_generation_manifest(backend, ChunkGeneration::B)?,
        ),
    ];
    if let Some(WindowsRootLayout::V3 {
        generation, count, ..
    }) = layout.as_ref()
    {
        let (_, bound) = generation_bounds
            .iter_mut()
            .find(|(candidate, _)| candidate == generation)
            .expect("both deterministic generations are present");
        *bound = (*bound).max(*count);
    }

    backend.delete(&WindowsCredentialSlot::Root)?;

    let mut cleanup = WindowsCleanupReport::default();
    for (generation, bound) in generation_bounds {
        let failures_before = cleanup.failures;
        for index in 0..bound {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Chunk { generation, index },
                &mut cleanup,
            );
        }
        if cleanup.failures == failures_before {
            cleanup_windows_slot(
                backend,
                WindowsCredentialSlot::V3Manifest(generation),
                &mut cleanup,
            );
        }
    }
    match layout {
        Some(WindowsRootLayout::LegacyV1 { count }) => {
            for index in 0..count {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::LegacyV1Chunk(index),
                    &mut cleanup,
                );
            }
        }
        Some(WindowsRootLayout::LegacyV2 { nonce, count }) => {
            for index in 0..count {
                cleanup_windows_slot(
                    backend,
                    WindowsCredentialSlot::LegacyV2Chunk {
                        nonce: nonce.clone(),
                        index,
                    },
                    &mut cleanup,
                );
            }
        }
        _ => {}
    }
    if let Some((nonce, count)) = retired_v2 {
        cleanup_retired_v2(backend, &nonce, count, &mut cleanup);
    }
    Ok(cleanup)
}

#[cfg(not(target_os = "macos"))]
fn platform_put(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_put(&dir, r, value);
    }
    // Windows-only: chunk an oversized secret. Runtime-gated so Linux Secret
    // Service (no size limit) keeps its exact single-entry behavior.
    if cfg!(windows) {
        // Always clear stale chunks first so a shrink (large → small) can't
        // leave orphans behind.
        clear_chunks(store, r);
        if value.encode_utf16().count() > CHUNK_THRESHOLD_UTF16 {
            let parts = split_on_chars(value, CHUNK_CHARS);
            for (i, part) in parts.iter().enumerate() {
                let cr = chunk_ref(r, i);
                store
                    .entry(&cr)?
                    .set_password(part)
                    .map_err(|e| classify(e, "set_password(chunk)"))?;
            }
            // The sentinel goes last so a reader never sees it before its
            // chunks exist.
            let sentinel = format!("{CHUNK_SENTINEL}{}", parts.len());
            return store
                .entry(r)?
                .set_password(&sentinel)
                .map_err(|e| classify(e, "set_password(sentinel)"));
        }
    }
    let entry = store.entry(r)?;
    entry
        .set_password(value)
        .map_err(|e| classify(e, "set_password"))
}

#[cfg(target_os = "windows")]
struct KeyringWindowsBackend<'a> {
    store: &'a SecretStore,
    root: &'a SecretRef,
}

#[cfg(target_os = "windows")]
impl KeyringWindowsBackend<'_> {
    fn secret_ref(&self, slot: &WindowsCredentialSlot) -> SecretRef {
        match slot {
            WindowsCredentialSlot::Root => self.root.clone(),
            WindowsCredentialSlot::LegacyV1Chunk(index) => chunk_ref(self.root, *index),
            WindowsCredentialSlot::LegacyV2Chunk { nonce, index } => {
                chunk_v2_ref(self.root, nonce, *index)
            }
            WindowsCredentialSlot::V3Chunk { generation, index } => {
                chunk_v3_ref(self.root, *generation, *index)
            }
            WindowsCredentialSlot::V3Manifest(generation) => {
                chunk_v3_manifest_ref(self.root, *generation)
            }
            WindowsCredentialSlot::RetiredV2Manifest => chunk_v3_retired_v2_ref(self.root),
        }
    }
}

#[cfg(target_os = "windows")]
impl WindowsCredentialBackend for KeyringWindowsBackend<'_> {
    fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
        match self.store.entry(&self.secret_ref(slot))?.get_password() {
            Ok(value) => Ok(Some(value)),
            Err(keyring::Error::NoEntry) => Ok(None),
            Err(error) => Err(classify(error, "get_password(windows-publish)")),
        }
    }

    fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
        self.store
            .entry(&self.secret_ref(slot))?
            .set_password(value)
            .map_err(|error| classify(error, "set_password(windows-publish)"))
    }

    fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
        match self
            .store
            .entry(&self.secret_ref(slot))?
            .delete_credential()
        {
            Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
            Err(error) => Err(classify(error, "delete_credential(windows-publish)")),
        }
    }
}

#[cfg(target_os = "windows")]
fn platform_publish(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    let cleanup = publish_windows_value(&mut backend, value)?;
    if cleanup.failures > 0 {
        tracing::warn!(
            cleanup_failures = cleanup.failures,
            "Windows credential publication committed; bounded cleanup deferred"
        );
    }
    Ok(())
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_publish(store: &SecretStore, r: &SecretRef, value: &str) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_publish(&dir, r, value);
    }
    store
        .entry(r)?
        .set_password(value)
        .map_err(|error| classify(error, "publish_password"))
}

#[cfg(target_os = "macos")]
fn platform_get(_store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    mac_get_via_security_cli(r)
}

#[cfg(target_os = "windows")]
fn platform_get(store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    match read_windows_value(&mut backend)? {
        Some(value) => Ok(value),
        None => Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        }),
    }
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_get(store: &SecretStore, r: &SecretRef) -> Result<String, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_get(&dir, r);
    }
    match store.entry(r)?.get_password() {
        Ok(value) => Ok(value),
        Err(keyring::Error::NoEntry) => Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        }),
        Err(error) => Err(classify(error, "get_password")),
    }
}

#[cfg(target_os = "macos")]
fn platform_delete(_store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    mac_delete_via_security_cli(r)
}

#[cfg(target_os = "windows")]
fn platform_delete(store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    let mut backend = KeyringWindowsBackend { store, root: r };
    let cleanup = delete_windows_value(&mut backend)?;
    if cleanup.failures > 0 {
        tracing::warn!(
            cleanup_failures = cleanup.failures,
            "Windows credential root deleted; bounded cleanup deferred"
        );
    }
    Ok(())
}

#[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
fn platform_delete(store: &SecretStore, r: &SecretRef) -> Result<(), SecretError> {
    if let Some(dir) = file_backend_dir() {
        return file_backend_delete(&dir, r);
    }
    match store.entry(r)?.delete_credential() {
        Ok(_) | Err(keyring::Error::NoEntry) => Ok(()),
        Err(error) => Err(classify(error, "delete_credential")),
    }
}

#[cfg(target_os = "macos")]
fn platform_status(_store: &SecretStore, r: &SecretRef) -> Result<SecretStatus, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return Ok(file_backend_status(&dir, r));
    }
    mac_status_via_security_cli(r)
}

#[cfg(not(target_os = "macos"))]
fn platform_status(store: &SecretStore, r: &SecretRef) -> Result<SecretStatus, SecretError> {
    if let Some(dir) = file_backend_dir() {
        return Ok(file_backend_status(&dir, r));
    }
    let entry = store.entry(r)?;
    let exists = match entry.get_password() {
        Ok(_) => true,
        Err(keyring::Error::NoEntry) => false,
        Err(other) => return Err(classify(other, "status")),
    };
    Ok(SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        exists,
    })
}

/// macOS usability probe: fail fast on a locked keychain, then exercise the
/// same real write path used by callers.
///
/// `SecKeychainGetStatus` is only a non-prompting preflight. Its writable bit
/// does not prove that this non-interactive process may create or update an
/// item, so availability also reads and writes CAR's fixed non-secret sentinel
/// through the Apple-signed helper (Parslee-ai/car#1158). The sentinel remains
/// in place; repeated probes update it and never introduce a delete gap.
#[cfg(target_os = "macos")]
fn platform_availability(_store: &SecretStore) -> AvailabilityCheck {
    mac_availability_via_security_cli_with(&SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_availability_via_security_cli_with(cli: &impl SecurityCli) -> AvailabilityCheck {
    let probe = SecretRef::new(SecretStore::PROBE_SERVICE, SecretStore::PROBE_KEY);
    let result = mac_exists_via_security_cli_with(&probe, cli).and_then(|_| {
        mac_put_via_security_cli_with(&probe.service, &probe.key, SecretStore::PROBE_VALUE, cli)
    });
    match result {
        Ok(()) => AvailabilityCheck {
            available: true,
            reason: None,
        },
        Err(error) => AvailabilityCheck {
            available: false,
            reason: Some(error.to_string()),
        },
    }
}

#[cfg(not(target_os = "macos"))]
fn platform_availability(store: &SecretStore) -> AvailabilityCheck {
    let probe = SecretRef::new(SecretStore::PROBE_SERVICE, SecretStore::PROBE_KEY);
    match store.entry(&probe) {
        Ok(entry) => match entry.get_password() {
            Ok(_) | Err(keyring::Error::NoEntry) => AvailabilityCheck {
                available: true,
                reason: None,
            },
            Err(keyring::Error::PlatformFailure(e)) => AvailabilityCheck {
                available: false,
                reason: Some(format!("platform failure: {e}")),
            },
            Err(keyring::Error::NoStorageAccess(e)) => AvailabilityCheck {
                available: false,
                reason: Some(format!("no storage access: {e}")),
            },
            // Other keyring errors (BadEncoding etc.) on the
            // probe key indicate the backend responded but
            // returned something unexpected. Treat as available
            // so the caller can still try real ops; the failure
            // mode shows up at the next put/get with proper
            // typed error.
            Err(_) => AvailabilityCheck {
                available: true,
                reason: None,
            },
        },
        Err(SecretError::Unavailable(reason)) => AvailabilityCheck {
            available: false,
            reason: Some(reason),
        },
        Err(other) => AvailabilityCheck {
            available: false,
            reason: Some(other.to_string()),
        },
    }
}

/// Shell-out write with the `-A` flag (any-app ACL).
///
/// `service`/`account` are passed as separate argv tokens so shell
/// metacharacters in either are inert. The value is the only argv slot
/// that's a secret; document the trade-off at the call site.
///
/// `-U` updates an existing item in place, preserving every authorization and
/// partition grant already attached to it. CAR never delete-recreates an item
/// as part of a write or a prompted-read repair. On a genuine create, `-A`
/// gives the stable Apple-signed helper access (car-0o9).
#[cfg(target_os = "macos")]
fn mac_put_via_security_cli(service: &str, account: &str, value: &str) -> Result<(), SecretError> {
    mac_put_via_security_cli_with(service, account, value, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_publish_via_security_cli(
    service: &str,
    account: &str,
    value: &str,
) -> Result<(), SecretError> {
    mac_publish_via_security_cli_with(service, account, value, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_publish_via_security_cli_with(
    service: &str,
    account: &str,
    value: &str,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    mac_write_via_security_cli(service, account, value, cli)
}

#[cfg(target_os = "macos")]
fn mac_put_via_security_cli_with(
    service: &str,
    account: &str,
    value: &str,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    mac_write_via_security_cli(service, account, value, cli)
}

/// Write or update a secret without replacing its ACL or partition list.
///
/// `add-generic-password -U` updates an existing item in place. On a create,
/// `-A` grants the stable Apple-signed `/usr/bin/security` helper access. CAR
/// never delete-recreates an item as a repair: doing so discards the partition
/// grants macOS persisted when the user approved a prior read and starts the
/// password-prompt cycle over (car-0o9).
#[cfg(target_os = "macos")]
fn mac_write_via_security_cli(
    service: &str,
    account: &str,
    value: &str,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    let output = cli.output(&[
        "add-generic-password",
        "-U", // update in place when the item is still there
        "-A", // permissive ACL — honoured only on a create
        "-s",
        service,
        "-a",
        account,
        "-w",
        value,
    ])?;
    if output.success {
        return Ok(());
    }
    Err(security_cli_backend_error("add-generic-password", output))
}

#[cfg(target_os = "macos")]
const SECURITY_ERR_SEC_ITEM_NOT_FOUND: i32 = 44;

#[cfg(target_os = "macos")]
#[derive(Debug)]
struct SecurityCliOutput {
    success: bool,
    code: Option<i32>,
    stdout: Vec<u8>,
    stderr: Vec<u8>,
}

#[cfg(target_os = "macos")]
trait SecurityCli {
    fn output(&self, args: &[&str]) -> Result<SecurityCliOutput, SecretError>;
}

#[cfg(target_os = "macos")]
struct SystemSecurityCli;

#[cfg(target_os = "macos")]
impl SecurityCli for SystemSecurityCli {
    fn output(&self, args: &[&str]) -> Result<SecurityCliOutput, SecretError> {
        let keychain_path = selected_keychain_path()
            .map_err(|error| SecretError::Backend(format!("select macOS keychain: {error}")))?;
        let access = MacKeychainAccess::for_security_args(args);
        let operation = args.first().copied().unwrap_or("security");
        let mut command = std::process::Command::new("/usr/bin/security");
        command.args(args);
        if let Some(path) = keychain_path.as_ref() {
            command.arg(path);
        }
        security_cli_output_after_preflight(command, operation, || {
            mac_keychain_preflight(keychain_path.as_deref(), access)
        })
    }
}

#[cfg(target_os = "macos")]
const KEYCHAIN_PATH_ENV: &str = "CAR_KEYCHAIN_PATH";

#[cfg(target_os = "macos")]
const KEYCHAIN_PROOF_ROOT_ENV: &str = "CAR_KEYCHAIN_PROOF_ROOT";

/// Resolve the optional release-proof Keychain selector. Production behavior
/// is unchanged when `CAR_KEYCHAIN_PATH` is absent.
#[cfg(target_os = "macos")]
fn selected_keychain_path() -> std::io::Result<Option<std::path::PathBuf>> {
    let Some(path) = std::env::var_os(KEYCHAIN_PATH_ENV).filter(|value| !value.is_empty()) else {
        return Ok(None);
    };
    let proof_root = std::env::var_os(KEYCHAIN_PROOF_ROOT_ENV)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!("{KEYCHAIN_PATH_ENV} requires {KEYCHAIN_PROOF_ROOT_ENV}"),
            )
        })?;
    validate_keychain_path(
        std::path::Path::new(&path),
        std::path::Path::new(&proof_root),
    )
    .map(Some)
}

#[cfg(target_os = "macos")]
fn validate_keychain_path(
    path: &std::path::Path,
    proof_root: &std::path::Path,
) -> std::io::Result<std::path::PathBuf> {
    use std::os::unix::fs::{MetadataExt, PermissionsExt};

    if !path.is_absolute() || !proof_root.is_absolute() {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidInput,
            "isolated Keychain path and proof root must be absolute",
        ));
    }

    let expected_uid = current_effective_uid();
    let root_metadata = std::fs::symlink_metadata(proof_root)?;
    if root_metadata.file_type().is_symlink()
        || !root_metadata.is_dir()
        || root_metadata.uid() != expected_uid
        || root_metadata.permissions().mode() & 0o077 != 0
    {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "Keychain proof root must be an owner-private, non-symlink directory owned by the current user",
        ));
    }

    let path_metadata = std::fs::symlink_metadata(path)?;
    if path_metadata.file_type().is_symlink()
        || !path_metadata.is_file()
        || path_metadata.uid() != expected_uid
        || path_metadata.permissions().mode() & 0o077 != 0
    {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "isolated Keychain must be an owner-private, non-symlink regular file owned by the current user",
        ));
    }

    let canonical_root = std::fs::canonicalize(proof_root)?;
    let canonical_path = std::fs::canonicalize(path)?;
    if !canonical_path.starts_with(&canonical_root) || canonical_path == canonical_root {
        return Err(std::io::Error::new(
            std::io::ErrorKind::PermissionDenied,
            "isolated Keychain must be canonically contained by its proof root",
        ));
    }
    Ok(canonical_path)
}

#[cfg(target_os = "macos")]
fn current_effective_uid() -> u32 {
    unsafe extern "C" {
        fn geteuid() -> u32;
    }
    // SAFETY: `geteuid` takes no arguments and has no preconditions.
    unsafe { geteuid() }
}

#[cfg(target_os = "macos")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MacKeychainAccess {
    Read,
    Write,
}

#[cfg(target_os = "macos")]
impl MacKeychainAccess {
    fn for_security_args(args: &[&str]) -> Self {
        match args.first().copied() {
            Some("find-generic-password") => Self::Read,
            _ => Self::Write,
        }
    }
}

#[cfg(target_os = "macos")]
const KEYCHAIN_UNLOCKED: u32 = 1;
#[cfg(target_os = "macos")]
const KEYCHAIN_READABLE: u32 = 2;
#[cfg(target_os = "macos")]
const KEYCHAIN_WRITABLE: u32 = 4;

#[cfg(target_os = "macos")]
fn mac_keychain_status_allows(status: u32, access: MacKeychainAccess) -> bool {
    let required = KEYCHAIN_UNLOCKED
        | KEYCHAIN_READABLE
        | match access {
            MacKeychainAccess::Read => 0,
            MacKeychainAccess::Write => KEYCHAIN_WRITABLE,
        };
    status & required == required
}

#[cfg(target_os = "macos")]
fn mac_keychain_preflight(
    path: Option<&std::path::Path>,
    access: MacKeychainAccess,
) -> Result<(), SecretError> {
    mac_keychain_preflight_status(mac_keychain_status(path)?, access)
}

#[cfg(target_os = "macos")]
fn mac_keychain_preflight_status(
    status: u32,
    access: MacKeychainAccess,
) -> Result<(), SecretError> {
    if status & KEYCHAIN_UNLOCKED == 0 {
        return Err(SecretError::Unavailable(
            "macOS keychain is locked; unlock it before retrying (no security helper was started)"
                .to_string(),
        ));
    }
    if !mac_keychain_status_allows(status, access) {
        let operation = match access {
            MacKeychainAccess::Read => "readable",
            MacKeychainAccess::Write => "readable and writable",
        };
        return Err(SecretError::Unavailable(format!(
            "macOS keychain is not {operation} (no security helper was started)"
        )));
    }
    Ok(())
}

#[cfg(target_os = "macos")]
fn mac_keychain_status(path: Option<&std::path::Path>) -> Result<u32, SecretError> {
    use std::os::unix::ffi::OsStrExt;

    #[link(name = "Security", kind = "framework")]
    unsafe extern "C" {
        #[link_name = "SecKeychainOpen"]
        fn sec_keychain_open(path: *const libc::c_char, keychain: *mut *mut libc::c_void) -> i32;
        #[link_name = "SecKeychainGetStatus"]
        fn sec_keychain_get_status(keychain: *mut libc::c_void, status: *mut u32) -> i32;
    }
    #[link(name = "CoreFoundation", kind = "framework")]
    unsafe extern "C" {
        #[link_name = "CFRelease"]
        fn cf_release(value: *const libc::c_void);
    }

    let mut opened_keychain = std::ptr::null_mut();
    if let Some(path) = path {
        let path = std::ffi::CString::new(path.as_os_str().as_bytes()).map_err(|_| {
            SecretError::Backend("selected macOS keychain path contains a NUL byte".to_string())
        })?;
        // SAFETY: `path` is NUL-terminated for the duration of the call and
        // `opened_keychain` points to writable storage for the retained result.
        let code = unsafe { sec_keychain_open(path.as_ptr(), &mut opened_keychain) };
        if code != 0 {
            if !opened_keychain.is_null() {
                // SAFETY: a non-null result from SecKeychainOpen is retained.
                unsafe { cf_release(opened_keychain) };
            }
            return Err(SecretError::Unavailable(format!(
                "macOS keychain status probe could not open the selected keychain: code={code}"
            )));
        }
    }

    let mut status = 0_u32;
    // SecKeychainGetStatus explicitly accepts NULL to select the default
    // keychain. It reads lock/read/write state only and does not access an item
    // or display an authorization prompt.
    // SAFETY: the keychain is either NULL (documented default) or a retained
    // SecKeychainRef, and `status` points to writable storage.
    let code = unsafe { sec_keychain_get_status(opened_keychain, &mut status) };
    if !opened_keychain.is_null() {
        // SAFETY: SecKeychainOpen returned this retained reference.
        unsafe { cf_release(opened_keychain) };
    }
    if code != 0 {
        return Err(SecretError::Unavailable(format!(
            "macOS keychain status probe failed: code={code}"
        )));
    }
    Ok(status)
}

/// One process-owned helper may run at a time. Caller deadlines never end the
/// helper: its worker keeps draining/reaping it until its natural exit.
#[cfg(target_os = "macos")]
struct SecurityCliExecutor {
    in_flight: std::sync::Arc<std::sync::atomic::AtomicBool>,
    timeout: std::time::Duration,
}

#[cfg(target_os = "macos")]
impl SecurityCliExecutor {
    fn new(timeout: std::time::Duration) -> Self {
        Self {
            in_flight: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
            timeout,
        }
    }

    fn output(
        &self,
        mut command: std::process::Command,
        operation: &str,
        preflight: impl FnOnce() -> Result<(), SecretError>,
    ) -> Result<SecurityCliOutput, SecretError> {
        use std::sync::atomic::Ordering;
        preflight()?;
        if self
            .in_flight
            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
            .is_err()
        {
            return Err(SecretError::Unavailable(
                "macOS keychain helper is still pending; finish or dismiss its authorization prompt, then retry (no additional helper started)".into(),
            ));
        }
        // Owned by the worker, including on caller timeout/disconnection.
        // Dropping the closure on thread-spawn failure also clears the gate.
        struct Flight(std::sync::Arc<std::sync::atomic::AtomicBool>);
        impl Drop for Flight {
            fn drop(&mut self) {
                self.0.store(false, Ordering::Release);
            }
        }
        let flight = Flight(self.in_flight.clone());
        let operation_owned = operation.to_owned();
        let (sender, receiver) = std::sync::mpsc::sync_channel(1);
        std::thread::Builder::new()
            .name("car-keychain-helper".into())
            .spawn(move || {
                let flight = flight;
                command.stdin(std::process::Stdio::null());
                let result = command
                    .output()
                    .map(|output| SecurityCliOutput {
                        success: output.status.success(),
                        code: output.status.code(),
                        stdout: output.stdout,
                        stderr: output.stderr,
                    })
                    .map_err(|error| security_cli_spawn_error(&operation_owned, error));
                // A late result is discarded, never cached as current credential
                // truth after the caller gave up. No signal is sent to the child.
                drop(flight);
                let _ = sender.send(result);
            })
            .map_err(|error| security_cli_spawn_error(operation, error))?;
        receiver.recv_timeout(self.timeout).map_err(|error| {
            SecretError::Unavailable(match error {
                std::sync::mpsc::RecvTimeoutError::Timeout =>
                    "macOS keychain helper is still pending; finish or dismiss its authorization prompt, then retry (helper retained without termination)".into(),
                std::sync::mpsc::RecvTimeoutError::Disconnected =>
                    "macOS keychain helper worker disconnected; retry the credential operation".into(),
            })
        })?
    }
}

/// The 15-second caller bound releases outer credential-coordinator locks.
/// Retry while the owned helper is pending fails promptly without another spawn.
#[cfg(target_os = "macos")]
fn security_cli_output_after_preflight(
    command: std::process::Command,
    operation: &str,
    preflight: impl FnOnce() -> Result<(), SecretError>,
) -> Result<SecurityCliOutput, SecretError> {
    static EXECUTOR: std::sync::OnceLock<SecurityCliExecutor> = std::sync::OnceLock::new();
    EXECUTOR
        .get_or_init(|| SecurityCliExecutor::new(std::time::Duration::from_secs(15)))
        .output(command, operation, preflight)
}

/// Primary macOS value read:
/// `/usr/bin/security find-generic-password -s SVC -a KEY -g`.
/// `-g` prints the password metadata line to stderr and preserves the
/// password bytes as hex when the value contains non-printable UTF-8
/// bytes. Service/key are passed as separate argv values, never
/// interpolated into a shell, so there's no injection surface even if a
/// key contains shell metacharacters.
#[cfg(target_os = "macos")]
fn mac_get_via_security_cli(r: &SecretRef) -> Result<String, SecretError> {
    mac_get_via_security_cli_with(r, &SystemSecurityCli)
}

/// CAR deliberately performs no automatic ACL or partition repair after a read.
///
/// A successful Keychain prompt is itself the user's persisted grant. Rewriting
/// or recreating the item here would discard that grant, and a partition-list
/// reconciliation through `security set-generic-password-partition-list` can
/// itself require another password prompt in an unattended daemon. The safe
/// persistence rule is therefore: read only, leave every existing item intact,
/// and let all future writes update it in place (car-0o9).
#[cfg(target_os = "macos")]
fn mac_get_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<String, SecretError> {
    let output = cli.output(&[
        "find-generic-password",
        "-s",
        &r.service,
        "-a",
        &r.key,
        "-g",
    ])?;
    if !output.success {
        return security_cli_not_found_or_backend("find-generic-password", r, output);
    }
    mac_parse_security_cli_password(&output)
}

#[cfg(target_os = "macos")]
fn mac_parse_security_cli_password(output: &SecurityCliOutput) -> Result<String, SecretError> {
    let line = mac_security_cli_text(&output.stderr, "stderr")?
        .lines()
        .find(|line| line.starts_with("password:"))
        .or_else(|| {
            mac_security_cli_text(&output.stdout, "stdout")
                .ok()
                .and_then(|stdout| stdout.lines().find(|line| line.starts_with("password:")))
        })
        .ok_or_else(|| {
            SecretError::Backend(
                "/usr/bin/security find-generic-password -g did not print a password line"
                    .to_string(),
            )
        })?;

    let payload = line
        .strip_prefix("password:")
        .expect("password line prefix was checked")
        .trim_start();

    if payload.is_empty() {
        return Ok(String::new());
    }

    let bytes = if let Some(hex_and_preview) = payload.strip_prefix("0x") {
        mac_decode_security_cli_hex_password(hex_and_preview)?
    } else {
        mac_decode_security_cli_quoted_password(payload)?
    };

    String::from_utf8(bytes).map_err(|e| {
        SecretError::Backend(format!(
            "/usr/bin/security find-generic-password password was not valid utf-8: {}",
            e
        ))
    })
}

#[cfg(target_os = "macos")]
fn mac_security_cli_text<'a>(bytes: &'a [u8], stream: &str) -> Result<&'a str, SecretError> {
    std::str::from_utf8(bytes).map_err(|e| {
        SecretError::Backend(format!(
            "/usr/bin/security find-generic-password {stream} was not valid utf-8: {e}"
        ))
    })
}

#[cfg(target_os = "macos")]
fn mac_decode_security_cli_hex_password(hex_and_preview: &str) -> Result<Vec<u8>, SecretError> {
    let hex: String = hex_and_preview
        .chars()
        .take_while(|c| c.is_ascii_hexdigit())
        .collect();
    if hex.is_empty() || !hex.len().is_multiple_of(2) {
        return Err(SecretError::Backend(format!(
            "/usr/bin/security find-generic-password printed invalid password hex: {hex:?}"
        )));
    }

    (0..hex.len())
        .step_by(2)
        .map(|i| {
            u8::from_str_radix(&hex[i..i + 2], 16).map_err(|e| {
                SecretError::Backend(format!(
                    "/usr/bin/security find-generic-password printed invalid password hex: {e}"
                ))
            })
        })
        .collect()
}

#[cfg(target_os = "macos")]
fn mac_decode_security_cli_quoted_password(payload: &str) -> Result<Vec<u8>, SecretError> {
    let quoted = payload.strip_prefix('"').and_then(|s| s.strip_suffix('"'));
    match quoted {
        Some(value) => Ok(value.as_bytes().to_vec()),
        None => Err(SecretError::Backend(
            "/usr/bin/security find-generic-password printed an unrecognized password line"
                .to_string(),
        )),
    }
}

#[cfg(target_os = "macos")]
fn mac_status_via_security_cli(r: &SecretRef) -> Result<SecretStatus, SecretError> {
    mac_status_via_security_cli_with(r, &SystemSecurityCli)
}

#[cfg(target_os = "macos")]
fn mac_status_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<SecretStatus, SecretError> {
    let exists = mac_exists_via_security_cli_with(r, cli)?;
    Ok(SecretStatus {
        service: r.service.clone(),
        key: r.key.clone(),
        exists,
    })
}

/// Existence-only shell-out: `security find-generic-password -s SVC -a KEY`
/// (no `-w`). Exit 0 means found, exit 44 means absent. Other non-zero
/// exits are backend/authorization errors and must not fall through to
/// an in-process API that can prompt again under the caller binary's CDHash.
#[cfg(target_os = "macos")]
fn mac_exists_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<bool, SecretError> {
    let output = cli.output(&["find-generic-password", "-s", &r.service, "-a", &r.key])?;
    if output.success {
        return Ok(true);
    }
    if output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Ok(false);
    }
    Err(security_cli_backend_error("find-generic-password", output))
}

#[cfg(target_os = "macos")]
fn mac_delete_via_security_cli(r: &SecretRef) -> Result<(), SecretError> {
    mac_delete_via_security_cli_with(r, &SystemSecurityCli)
}

/// Primary macOS delete. Treats "no such item" as success to preserve
/// the public idempotent delete contract.
#[cfg(target_os = "macos")]
fn mac_delete_via_security_cli_with(
    r: &SecretRef,
    cli: &impl SecurityCli,
) -> Result<(), SecretError> {
    let output = cli.output(&["delete-generic-password", "-s", &r.service, "-a", &r.key])?;
    if output.success || output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Ok(());
    }
    Err(security_cli_backend_error(
        "delete-generic-password",
        output,
    ))
}

#[cfg(target_os = "macos")]
fn security_cli_not_found_or_backend<T>(
    command: &str,
    r: &SecretRef,
    output: SecurityCliOutput,
) -> Result<T, SecretError> {
    if output.code == Some(SECURITY_ERR_SEC_ITEM_NOT_FOUND) {
        return Err(SecretError::NotFound {
            service: r.service.clone(),
            key: r.key.clone(),
        });
    }
    Err(security_cli_backend_error(command, output))
}

#[cfg(target_os = "macos")]
fn security_cli_spawn_error(command: &str, e: std::io::Error) -> SecretError {
    SecretError::Backend(format!("/usr/bin/security {command} spawn: {e}"))
}

#[cfg(target_os = "macos")]
fn security_cli_backend_error(command: &str, output: SecurityCliOutput) -> SecretError {
    let stderr = String::from_utf8_lossy(&output.stderr);
    let code = output.code.unwrap_or(-1);
    match classify_security_error(code, stderr.trim()) {
        SecretError::Backend(_) => SecretError::Backend(format!(
            "/usr/bin/security {command} failed: code={code} {}",
            stderr.trim()
        )),
        typed => typed,
    }
}

#[cfg(target_os = "macos")]
fn classify_security_error(code: i32, detail: &str) -> SecretError {
    let normalized = detail.to_ascii_lowercase();
    if code == -128 || (code == 128 && normalized.contains("cancel")) {
        return SecretError::UserCancelled {
            message: detail.to_string(),
        };
    }
    if code == -25293
        || code == 51
        || normalized.contains("authorization denied")
        || normalized.contains("auth denied")
        || normalized.contains("interaction is not allowed")
    {
        return SecretError::AccessDenied {
            message: detail.to_string(),
        };
    }
    SecretError::Backend(format!("macOS security error: code={code} {detail}"))
}

/// Map keyring crate errors into our typed error set.
///
/// Not compiled on macOS: nothing there reaches the keyring crate, so there
/// are no keyring errors to classify. The macOS equivalents are
/// `security_cli_backend_error` and `security_cli_not_found_or_backend`.
#[cfg(not(target_os = "macos"))]
fn classify(e: keyring::Error, op: &str) -> SecretError {
    use keyring::Error as K;
    match e {
        K::NoEntry => SecretError::NotFound {
            service: String::new(),
            key: String::new(),
        },
        K::PlatformFailure(inner) => SecretError::Unavailable(format!("{}: {}", op, inner)),
        K::NoStorageAccess(inner) => SecretError::Unavailable(format!("{}: {}", op, inner)),
        K::BadEncoding(_) => SecretError::Backend(format!("{}: value encoding", op)),
        other => SecretError::Backend(format!("{}: {}", op, other)),
    }
}

#[cfg(test)]
mod chunk_tests {
    use super::*;
    use std::collections::BTreeMap;

    #[test]
    fn split_on_chars_covers_boundaries() {
        assert_eq!(split_on_chars("", 3), Vec::<String>::new());
        assert_eq!(split_on_chars("abc", 3), vec!["abc"]);
        assert_eq!(split_on_chars("abcd", 3), vec!["abc", "d"]);
        assert_eq!(split_on_chars("abcdef", 2), vec!["ab", "cd", "ef"]);
        // Reassembly is lossless for a value well past the Windows blob cap.
        let big: String = "x".repeat(4000);
        let joined: String = split_on_chars(&big, CHUNK_CHARS).concat();
        assert_eq!(joined, big);
    }

    #[test]
    fn sentinel_round_trips_the_chunk_count() {
        let n = split_on_chars(&"y".repeat(3300), CHUNK_CHARS).len();
        let sentinel = format!("{CHUNK_SENTINEL}{n}");
        let parsed = sentinel
            .strip_prefix(CHUNK_SENTINEL)
            .and_then(|s| s.parse::<usize>().ok());
        assert_eq!(parsed, Some(4)); // 3300 / 1000 -> 4 chunks
                                     // A real (non-chunked) value is never mistaken for a sentinel.
        assert!("eyJhbGciOi.reallongjwt"
            .strip_prefix(CHUNK_SENTINEL)
            .is_none());
    }

    #[test]
    fn threshold_leaves_small_values_inline() {
        // A value at/under the threshold must NOT be chunked (single entry,
        // backward compatible with pre-existing secrets).
        assert!("short-api-key".encode_utf16().count() <= CHUNK_THRESHOLD_UTF16);
        assert!("z".repeat(2001).encode_utf16().count() > CHUNK_THRESHOLD_UTF16);
    }

    #[derive(Debug, Clone)]
    struct FailureRule {
        slot: WindowsCredentialSlot,
        matches_to_skip: usize,
    }

    #[derive(Debug, Clone, Default)]
    struct MemoryWindowsBackend {
        entries: BTreeMap<WindowsCredentialSlot, String>,
        mutation_calls: usize,
        crash_after_mutation: Option<usize>,
        fail_write: Option<FailureRule>,
        fail_delete: Option<FailureRule>,
    }

    impl MemoryWindowsBackend {
        fn after_mutation(&mut self) {
            self.mutation_calls += 1;
            if self.crash_after_mutation == Some(self.mutation_calls) {
                panic!("injected Windows credential process crash");
            }
        }

        fn should_fail(rule: &mut Option<FailureRule>, slot: &WindowsCredentialSlot) -> bool {
            let Some(candidate) = rule.as_mut() else {
                return false;
            };
            if &candidate.slot != slot {
                return false;
            }
            if candidate.matches_to_skip > 0 {
                candidate.matches_to_skip -= 1;
                return false;
            }
            *rule = None;
            true
        }

        fn reset_faults(&mut self) {
            self.mutation_calls = 0;
            self.crash_after_mutation = None;
            self.fail_write = None;
            self.fail_delete = None;
        }

        fn root(&self) -> String {
            self.entries
                .get(&WindowsCredentialSlot::Root)
                .expect("root credential")
                .clone()
        }
    }

    impl WindowsCredentialBackend for MemoryWindowsBackend {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            Ok(self.entries.get(slot).cloned())
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            if Self::should_fail(&mut self.fail_write, slot) {
                return Err(SecretError::Backend(
                    "injected Windows credential write failure".to_string(),
                ));
            }
            self.entries.insert(slot.clone(), value.to_string());
            self.after_mutation();
            Ok(())
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            if Self::should_fail(&mut self.fail_delete, slot) {
                return Err(SecretError::Backend(
                    "injected Windows credential cleanup failure".to_string(),
                ));
            }
            self.entries.remove(slot);
            self.after_mutation();
            Ok(())
        }
    }

    fn publish(backend: &mut MemoryWindowsBackend, value: &str) -> WindowsCleanupReport {
        publish_windows_value(backend, value).expect("publication")
    }

    fn read(backend: &mut impl WindowsCredentialBackend) -> String {
        read_windows_value(backend)
            .expect("read succeeds")
            .expect("root exists")
    }

    fn legacy_v2(value: &str, nonce: &str) -> MemoryWindowsBackend {
        let mut backend = MemoryWindowsBackend::default();
        let chunks = split_on_chars(value, CHUNK_CHARS);
        backend.entries.insert(
            WindowsCredentialSlot::Root,
            format!("{CHUNK_SENTINEL_V2}{nonce}:{}", chunks.len()),
        );
        for (index, chunk) in chunks.into_iter().enumerate() {
            backend.entries.insert(
                WindowsCredentialSlot::LegacyV2Chunk {
                    nonce: nonce.to_string(),
                    index,
                },
                chunk,
            );
        }
        backend
    }

    fn assert_backend_error(error: SecretError, needle: &str) {
        match error {
            SecretError::Backend(message) => assert!(message.contains(needle), "{message}"),
            other => panic!("expected backend error, got {other:?}"),
        }
    }

    #[test]
    fn v3_publication_uses_revisioned_dual_generation_roots() {
        let value = "v".repeat(3300);
        let plan = chunk_publication_plan(&value, ChunkGeneration::B, "revision-7").unwrap();

        assert_eq!(plan.generation, ChunkGeneration::B);
        assert_eq!(plan.chunks.concat(), value);
        assert_eq!(
            windows_root_layout(&plan.root).unwrap(),
            WindowsRootLayout::V3 {
                generation: ChunkGeneration::B,
                revision: "revision-7".to_string(),
                count: 4,
            }
        );
        assert!(
            plan.chunks
                .iter()
                .all(|chunk| chunk.encode_utf16().count() <= CHUNK_CHARS),
            "every staged credential must remain below the platform cap"
        );
    }

    #[test]
    fn reader_capturing_old_root_finishes_after_writer_swaps_root() {
        let old = "old-".repeat(900);
        let new = "new-".repeat(900);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        let mut reader = InterleavingReader::new(backend, vec![new.as_str()]);
        assert_eq!(read(&mut reader), old);
        assert_eq!(read(&mut reader.inner), new);
    }

    #[test]
    fn reader_detects_generation_aba_and_retries_latest_root() {
        let old = "old-".repeat(900);
        let middle = "mid-".repeat(1100);
        let latest = "latest-".repeat(700);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        let mut reader = InterleavingReader::new(backend, vec![middle.as_str(), latest.as_str()]);
        assert_eq!(read(&mut reader), latest);
        assert!(reader.root_reads >= 4, "the ABA path must consume a retry");
    }

    #[test]
    fn legacy_nonce_chunks_survive_the_first_v3_root_swap_then_recover() {
        let old = "legacy-".repeat(700);
        let replacement = "replacement-".repeat(500);
        let followup = "followup-".repeat(500);
        let backend = legacy_v2(&old, "legacy-nonce");

        let mut reader = InterleavingReader::new(backend, vec![replacement.as_str()]);
        assert_eq!(read(&mut reader), old);
        assert!(reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::RetiredV2Manifest));
        assert!(reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::LegacyV2Chunk {
                nonce: "legacy-nonce".to_string(),
                index: 0,
            }));

        publish(&mut reader.inner, &followup);
        assert!(!reader
            .inner
            .entries
            .contains_key(&WindowsCredentialSlot::RetiredV2Manifest));
        assert!(!reader.inner.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::LegacyV2Chunk { nonce, .. } if nonce == "legacy-nonce"
        )));
    }

    #[test]
    fn crash_after_every_publish_mutation_preserves_a_readable_generation() {
        let old = "old-".repeat(1200);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(300);
        let mut base = MemoryWindowsBackend::default();
        publish(&mut base, &old);
        publish(&mut base, &current);
        base.reset_faults();

        let mut successful = base.clone();
        publish(&mut successful, &replacement);
        let mutation_count = successful.mutation_calls;
        assert!(mutation_count >= 7, "exercise stage, commit, and cleanup");

        for crash_after in 1..=mutation_count {
            let mut crashed = base.clone();
            crashed.crash_after_mutation = Some(crash_after);
            let unwind = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                let _ = publish_windows_value(&mut crashed, &replacement);
            }));
            assert!(unwind.is_err(), "mutation {crash_after} must crash");
            crashed.reset_faults();

            let observed = read(&mut crashed);
            assert!(
                observed == current || observed == replacement,
                "crash {crash_after} exposed neither committed generation"
            );

            publish(&mut crashed, &replacement);
            publish(&mut crashed, "recovery-pass");
            publish(&mut crashed, &replacement);
            assert_eq!(read(&mut crashed), replacement);
            assert!(
                crashed.entries.len() <= 20,
                "crash {crash_after} leaked unbounded entries: {:?}",
                crashed.entries.keys().collect::<Vec<_>>()
            );
        }
    }

    #[test]
    fn repeated_precommit_crashes_have_bounded_cardinality_and_recover_cleanup() {
        let old = "old-".repeat(900);
        let attempted = "attempted-".repeat(900);
        let recovered = "ok-".repeat(600);
        let attempted_chunks = split_on_chars(&attempted, CHUNK_CHARS).len();
        let old_chunks = split_on_chars(&old, CHUNK_CHARS).len();
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);

        for crash_index in 0..64 {
            backend.reset_faults();
            backend.crash_after_mutation = Some(1 + crash_index % attempted_chunks);
            let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                let _ = publish_windows_value(&mut backend, &attempted);
            }));
            assert!(
                backend.entries.len() <= 1 + 2 + old_chunks + attempted_chunks,
                "attempt {crash_index} grew deterministic storage"
            );
        }

        backend.reset_faults();
        publish(&mut backend, &recovered);
        assert_eq!(read(&mut backend), recovered);
        let recovered_chunks = split_on_chars(&recovered, CHUNK_CHARS).len();
        assert!(!backend.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::B,
                index,
            } if *index >= recovered_chunks
        )));
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::B)),
            Some(&recovered_chunks.to_string())
        );
    }

    #[test]
    fn staging_and_root_failures_leave_the_only_good_generation_readable() {
        let old = "old-".repeat(900);
        let replacement = "replacement-".repeat(500);
        for failed_slot in [
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::B,
                index: 1,
            },
            WindowsCredentialSlot::Root,
        ] {
            let mut backend = MemoryWindowsBackend::default();
            publish(&mut backend, &old);
            backend.fail_write = Some(FailureRule {
                slot: failed_slot,
                matches_to_skip: 0,
            });

            let error = publish_windows_value(&mut backend, &replacement).unwrap_err();
            assert_backend_error(error, "injected");
            assert_eq!(read(&mut backend), old);
        }
    }

    #[test]
    fn postcommit_cleanup_errors_report_deferred_success_and_recover_later() {
        let old = "old-".repeat(1400);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(200);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        publish(&mut backend, &current);
        backend.fail_delete = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index: 4,
            },
            matches_to_skip: 0,
        });

        let cleanup = publish_windows_value(&mut backend, &replacement).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert_eq!(read(&mut backend), replacement);
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)),
            Some(&split_on_chars(&old, CHUNK_CHARS).len().to_string()),
            "failed cleanup keeps the crash high-water for a later sweep"
        );

        publish(&mut backend, "rotate-once");
        publish(&mut backend, &replacement);
        assert!(!backend.entries.keys().any(|slot| matches!(
            slot,
            WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index,
            } if *index >= split_on_chars(&replacement, CHUNK_CHARS).len()
        )));
    }

    #[test]
    fn postcommit_manifest_shrink_failure_keeps_recovery_high_water() {
        let old = "old-".repeat(1400);
        let current = "current-".repeat(900);
        let replacement = "replacement-".repeat(200);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        publish(&mut backend, &current);
        backend.fail_write = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Manifest(ChunkGeneration::A),
            matches_to_skip: 1,
        });

        let cleanup = publish_windows_value(&mut backend, &replacement).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert_eq!(read(&mut backend), replacement);
        assert_eq!(
            backend
                .entries
                .get(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)),
            Some(&split_on_chars(&old, CHUNK_CHARS).len().to_string())
        );
    }

    #[test]
    fn delete_cleanup_failure_retains_manifest_for_idempotent_recovery() {
        let value = "secret-".repeat(700);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &value);
        backend.fail_delete = Some(FailureRule {
            slot: WindowsCredentialSlot::V3Chunk {
                generation: ChunkGeneration::A,
                index: 0,
            },
            matches_to_skip: 0,
        });

        let cleanup = delete_windows_value(&mut backend).unwrap();
        assert_eq!(cleanup.failures, 1);
        assert!(!backend.entries.contains_key(&WindowsCredentialSlot::Root));
        assert!(backend
            .entries
            .contains_key(&WindowsCredentialSlot::V3Manifest(ChunkGeneration::A)));

        backend.reset_faults();
        assert_eq!(delete_windows_value(&mut backend).unwrap().failures, 0);
        assert!(backend.entries.is_empty());
    }

    #[test]
    fn corrupt_cleanup_metadata_fails_before_root_or_chunks_are_deleted() {
        let old = "old-".repeat(900);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &old);
        let root_before = backend.root();
        backend.entries.insert(
            WindowsCredentialSlot::V3Manifest(ChunkGeneration::B),
            "not-a-count".to_string(),
        );

        let error = publish_windows_value(&mut backend, "replacement").unwrap_err();
        assert_backend_error(error, "manifest");
        assert_eq!(backend.root(), root_before);
        assert_eq!(read(&mut backend), old);

        let error = delete_windows_value(&mut backend).unwrap_err();
        assert_backend_error(error, "manifest");
        assert_eq!(backend.root(), root_before);
        assert_eq!(read(&mut backend), old);
    }

    #[test]
    fn reader_retry_is_bounded_when_root_never_stabilizes() {
        let value_a = "a".repeat(2500);
        let value_b = "b".repeat(2500);
        let mut backend = MemoryWindowsBackend::default();
        publish(&mut backend, &value_a);
        let root_a = backend.root();
        publish(&mut backend, &value_b);
        let root_b = backend.root();
        backend.entries.remove(&WindowsCredentialSlot::V3Chunk {
            generation: ChunkGeneration::A,
            index: 0,
        });
        let mut churning = AlternatingRootBackend {
            inner: backend,
            roots: [root_a, root_b],
            root_reads: 0,
        };

        let error = read_windows_value(&mut churning).unwrap_err();
        assert_backend_error(error, "changed during every read attempt");
        assert_eq!(churning.root_reads, WINDOWS_READ_ATTEMPTS * 2);
    }

    struct InterleavingReader<'a> {
        inner: MemoryWindowsBackend,
        publications: Vec<&'a str>,
        root_reads: usize,
    }

    impl<'a> InterleavingReader<'a> {
        fn new(inner: MemoryWindowsBackend, publications: Vec<&'a str>) -> Self {
            Self {
                inner,
                publications,
                root_reads: 0,
            }
        }
    }

    impl WindowsCredentialBackend for InterleavingReader<'_> {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            let captured = self.inner.read(slot)?;
            if slot == &WindowsCredentialSlot::Root && self.root_reads == 0 {
                for value in self.publications.drain(..) {
                    publish_windows_value(&mut self.inner, value)?;
                }
            }
            if slot == &WindowsCredentialSlot::Root {
                self.root_reads += 1;
            }
            Ok(captured)
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            self.inner.write(slot, value)
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            self.inner.delete(slot)
        }
    }

    struct AlternatingRootBackend {
        inner: MemoryWindowsBackend,
        roots: [String; 2],
        root_reads: usize,
    }

    impl WindowsCredentialBackend for AlternatingRootBackend {
        fn read(&mut self, slot: &WindowsCredentialSlot) -> Result<Option<String>, SecretError> {
            if slot == &WindowsCredentialSlot::Root {
                let root = self.roots[self.root_reads % self.roots.len()].clone();
                self.root_reads += 1;
                return Ok(Some(root));
            }
            self.inner.read(slot)
        }

        fn write(&mut self, slot: &WindowsCredentialSlot, value: &str) -> Result<(), SecretError> {
            self.inner.write(slot, value)
        }

        fn delete(&mut self, slot: &WindowsCredentialSlot) -> Result<(), SecretError> {
            self.inner.delete(slot)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde::{Deserialize, Serialize};

    /// An unusable store must not answer "that secret is absent".
    ///
    /// These three take no env lock: they call the file-backend helpers with an
    /// explicit `dir`, so they touch no process-global state.
    ///
    /// The distinction is invisible on unix, where an entry under a regular file
    /// fails with `ENOTDIR`, and load-bearing on Windows, where the same open
    /// returns `ERROR_PATH_NOT_FOUND` and Rust maps it to `NotFound`. Asserting
    /// it here keeps both platforms honest without needing a Windows runner to
    /// notice the regression.
    #[test]
    fn a_store_that_is_not_a_directory_is_a_backend_error_not_a_missing_secret() {
        let parent = tempfile::tempdir().unwrap();
        let not_a_dir = parent.path().join("blocked");
        std::fs::write(&not_a_dir, b"a regular file where the store should be").unwrap();
        let reference = SecretRef::with_default_service("SOME_KEY");

        assert!(
            !file_backend_entry_is_merely_absent(&not_a_dir),
            "the platform-neutral discriminator must reject a regular-file store root"
        );

        match file_backend_get(&not_a_dir, &reference) {
            Err(SecretError::Backend(_)) => {}
            other => panic!("unusable store must report a backend error, got {other:?}"),
        }
        match file_backend_delete(&not_a_dir, &reference) {
            Err(SecretError::Backend(_)) => {}
            other => panic!("unusable store must not report a successful delete, got {other:?}"),
        }
        assert!(
            !file_backend_status(&not_a_dir, &reference).exists,
            "status on an unusable store must not claim knowledge of the entry"
        );
    }

    /// A store directory that has not been created yet is a first run, not a
    /// broken store: only `put`/`publish` create it.
    #[test]
    fn a_store_directory_that_does_not_exist_yet_is_still_not_found() {
        let parent = tempfile::tempdir().unwrap();
        let never_created = parent.path().join("not-created-yet");
        assert!(!never_created.exists());
        assert!(
            file_backend_entry_is_merely_absent(&never_created),
            "a missing directory beneath an existing directory is a normal first run"
        );
        let reference = SecretRef::with_default_service("SOME_KEY");

        match file_backend_get(&never_created, &reference) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("a first-run store has no secrets, it is not broken: {other:?}"),
        }
        assert!(
            file_backend_delete(&never_created, &reference).is_ok(),
            "deleting from a store that was never written is a no-op success"
        );
        assert!(!file_backend_status(&never_created, &reference).exists);
    }

    #[test]
    fn a_missing_entry_in_a_real_directory_is_still_not_found() {
        let dir = tempfile::tempdir().unwrap();
        let reference = SecretRef::with_default_service("ABSENT_KEY");

        match file_backend_get(dir.path(), &reference) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("an absent entry in a usable store is NotFound, got {other:?}"),
        }
        assert!(
            file_backend_delete(dir.path(), &reference).is_ok(),
            "deleting an absent entry from a usable store is a no-op success"
        );
        assert!(!file_backend_status(dir.path(), &reference).exists);
    }

    /// Process-wide serialization lock for every test that touches the secret
    /// store. `CAR_SECRETS_FILE_DIR` is process-global, so an isolated-backend
    /// fixture must not change it while another store test is running.
    /// `unwrap_or_else(into_inner)` keeps the suite running if one test panics
    /// while holding it.
    static STORE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    fn lock_store() -> std::sync::MutexGuard<'static, ()> {
        STORE_LOCK.lock().unwrap_or_else(|e| e.into_inner())
    }

    /// Parallel-suite-safe fixture for public `SecretStore` contract tests.
    /// The lock makes the process environment transition atomic, while each
    /// fixture gets a fresh directory. `Drop` restores an inherited redirect
    /// rather than assuming the caller had none.
    struct IsolatedStoreFixture {
        _guard: std::sync::MutexGuard<'static, ()>,
        _dir: tempfile::TempDir,
        previous_dir: Option<std::ffi::OsString>,
    }

    impl IsolatedStoreFixture {
        fn new() -> Self {
            let guard = lock_store();
            let dir = tempfile::tempdir().expect("isolated secret-store directory");
            let previous_dir = std::env::var_os("CAR_SECRETS_FILE_DIR");
            std::env::set_var("CAR_SECRETS_FILE_DIR", dir.path());
            assert_eq!(
                file_backend_dir().as_deref(),
                Some(dir.path()),
                "contract test must use the isolated file backend"
            );
            Self {
                _guard: guard,
                _dir: dir,
                previous_dir,
            }
        }

        fn store(&self) -> SecretStore {
            SecretStore::new()
        }
    }

    impl Drop for IsolatedStoreFixture {
        fn drop(&mut self) {
            match self.previous_dir.take() {
                Some(value) => std::env::set_var("CAR_SECRETS_FILE_DIR", value),
                None => std::env::remove_var("CAR_SECRETS_FILE_DIR"),
            }
        }
    }

    struct ClearedEnv {
        name: &'static str,
        previous: Option<std::ffi::OsString>,
    }

    impl ClearedEnv {
        fn new(name: &'static str) -> Self {
            let previous = std::env::var_os(name);
            std::env::remove_var(name);
            Self { name, previous }
        }
    }

    impl Drop for ClearedEnv {
        fn drop(&mut self) {
            match self.previous.take() {
                Some(value) => std::env::set_var(self.name, value),
                None => std::env::remove_var(self.name),
            }
        }
    }

    // Provisioned native-keychain runs use a unique service name to avoid
    // colliding with real credentials a developer has in their keychain.
    #[cfg(target_os = "macos")]
    fn test_service() -> String {
        format!(
            "car-secrets-tests-{}-{}",
            std::process::id(),
            // Nanos since startup — good enough to isolate tests running
            // in parallel inside one process.
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        )
    }

    #[cfg(target_os = "macos")]
    const NATIVE_KEYCHAIN_LANE: &str = "CAR_TEST_NATIVE_KEYCHAIN";

    #[cfg(target_os = "macos")]
    fn run_native_keychain_lane() {
        assert!(
            std::env::var_os("CAR_SECRETS_FILE_DIR").is_none(),
            "native lane refuses CAR_SECRETS_FILE_DIR; run it against the provisioned keychain"
        );
        let store = SecretStore::new();
        let availability = store.availability();
        assert!(
            availability.available,
            "native keychain unavailable: {}",
            availability
                .reason
                .unwrap_or_else(|| "no reason reported".to_string())
        );

        #[derive(Serialize, Deserialize, PartialEq, Debug)]
        struct Session {
            cookies: Vec<String>,
            expires_at: i64,
        }

        let reference = SecretRef::new(test_service(), "provisioned-native-contracts");
        store
            .delete(&reference)
            .expect("clean native fixture before run");
        assert!(matches!(
            store.get(&reference),
            Err(SecretError::NotFound { .. })
        ));
        store.put(&reference, "abc\n").expect("write native secret");
        assert_eq!(store.get(&reference).unwrap(), "abc\n");
        let status = store.status(&reference).unwrap();
        assert!(status.exists);
        assert!(!serde_json::to_string(&status).unwrap().contains("abc"));
        let session = Session {
            cookies: vec!["a=1".into(), "b=2".into()],
            expires_at: 1_700_000_000,
        };
        store.put_json(&reference, &session).unwrap();
        assert_eq!(store.get_json::<Session>(&reference).unwrap(), session);
        store
            .delete(&reference)
            .expect("clean native fixture after run");
        store
            .delete(&reference)
            .expect("native delete is idempotent");
        assert!(!store.status(&reference).unwrap().exists);
    }

    /// S2 — the opt-in file backend is honored in a debug/test build, drives a
    /// real `put`/`get`/`delete` round-trip through the plaintext file path, and
    /// `availability` still reports healthy (it's just the local filesystem).
    ///
    /// `cargo test` builds with `debug_assertions` on, so `file_backend_dir()`
    /// honors `CAR_SECRETS_FILE_DIR` here. A RELEASE binary returns `None` from
    /// `file_backend_dir()` regardless — production can never reach this path.
    ///
    /// The env var is process-global; this test sets it, runs, then removes it.
    /// `STORE_LOCK` serializes that transition against the focused contract
    /// fixtures below.
    /// A `MakeWriter` that appends every emitted log line into a shared buffer
    /// so the test can assert the one-time file-backend warning actually fired.
    #[derive(Clone)]
    struct BufWriter(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);

    impl std::io::Write for BufWriter {
        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
            self.0.lock().unwrap().extend_from_slice(buf);
            Ok(buf.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for BufWriter {
        type Writer = BufWriter;
        fn make_writer(&'a self) -> Self::Writer {
            self.clone()
        }
    }

    #[test]
    fn file_backend_roundtrip_and_warn_under_debug() {
        const CHILD: &str = "CAR_TEST_FILE_BACKEND_WARNING_CHILD";
        if std::env::var_os(CHILD).is_none() {
            let output =
                std::process::Command::new(std::env::current_exe().expect("test executable"))
                    .args([
                        "--exact",
                        "tests::file_backend_roundtrip_and_warn_under_debug",
                        "--nocapture",
                    ])
                    .env(CHILD, "1")
                    .env_remove("CAR_SECRETS_FILE_DIR")
                    .env_remove("CAR_TEST_PRECONSUME_FILE_BACKEND_WARNING")
                    .env_remove("CAR_KEYCHAIN_PROOF_ROOT")
                    .env_remove("CAR_KEYCHAIN_PATH")
                    .output()
                    .expect("spawn isolated file-backend warning test");
            assert!(
                output.status.success(),
                "isolated file-backend warning test failed\nstdout:\n{}\nstderr:\n{}",
                String::from_utf8_lossy(&output.stdout),
                String::from_utf8_lossy(&output.stderr),
            );
            return;
        }

        // Test hook for the isolation regression: model another parallel test
        // engaging the process-wide file backend before this test installs its
        // tracing subscriber.
        if std::env::var_os("CAR_TEST_PRECONSUME_FILE_BACKEND_WARNING").is_some() {
            let _ = file_backend_dir();
        }
        // Hold the store lock for the WHOLE test: while the global redirect env
        // var is set, no parallel keychain test may run.
        let _guard = lock_store();
        // Sanity: this whole seam only exists in debug builds. The asserted
        // value is a compile-time constant on purpose — it documents the
        // debug-build dependency, so silence the constant-assertion lint.
        #[allow(clippy::assertions_on_constants)]
        {
            assert!(
                cfg!(debug_assertions),
                "the crate test suite runs in debug; the file backend depends on it"
            );
        }

        let dir = std::env::temp_dir().join(format!(
            "car-secrets-filebackend-{}-{}",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        ));
        std::fs::create_dir_all(&dir).unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", &dir);

        // Capture logs so we can assert the one-time warning fires the first
        // time the redirect engages in this process.
        let buf = std::sync::Arc::new(std::sync::Mutex::new(Vec::<u8>::new()));
        let subscriber = tracing_subscriber::fmt()
            .with_writer(BufWriter(buf.clone()))
            .with_max_level(tracing::Level::WARN)
            .finish();
        tracing::subscriber::with_default(subscriber, || {
            // The redirect is honored (Some) — and fires the one-time warn the
            // first time it engages in this process.
            assert_eq!(
                file_backend_dir().as_deref(),
                Some(dir.as_path()),
                "CAR_SECRETS_FILE_DIR must be honored under debug_assertions"
            );
        });
        let logged = String::from_utf8(buf.lock().unwrap().clone()).unwrap();
        assert!(
            logged.contains("PLAINTEXT ON DISK"),
            "the file backend must emit the one-time PLAINTEXT warning, got logs: {logged:?}"
        );

        let store = SecretStore::new();
        // availability_check still reports healthy on the file backend.
        let check = store.availability();
        assert!(check.available, "file backend must report available");
        assert!(check.reason.is_none());

        // Real put/get/delete round-trip through the plaintext file path.
        let r = SecretRef::new("svc", "key");
        store.put(&r, "xoxb-plaintext-value").unwrap();
        assert_eq!(store.get(&r).unwrap(), "xoxb-plaintext-value");
        // The value really is plaintext on disk (the documented trade-off).
        let on_disk = std::fs::read_to_string(file_backend_path(&dir, &r)).unwrap();
        assert_eq!(on_disk, "xoxb-plaintext-value");
        store.delete(&r).unwrap();
        match store.get(&r) {
            Err(SecretError::NotFound { .. }) => {}
            other => panic!("expected NotFound after delete, got {other:?}"),
        }

        // The reserved-slot guard lives in generic wrappers, not SecretStore:
        // Daemon-owned code must still be able to lease and delete every exact
        // internal slot directly even though generic wrappers reject them.
        for key in [
            OPENROUTER_OAUTH_KEY,
            PARSLEE_ACCESS_TOKEN_KEY,
            PARSLEE_REFRESH_TOKEN_KEY,
            PARSLEE_EXPIRES_AT_KEY,
            PARSLEE_API_BASE_KEY,
            PARSLEE_ACCOUNTS_KEY,
            "PARSLEE_TOKENS_account-1",
            PARSLEE_AUTH_GENERATION_KEY,
            PARSLEE_AUTH_COMPLETION_KEY,
            PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
            PARSLEE_AUTH_STATE_V2_KEY,
        ] {
            let private = SecretRef::new(DEFAULT_SERVICE, key);
            assert!(is_daemon_private_secret(&private.service, &private.key));
            store.put(&private, "internal-test-value").unwrap();
            assert_eq!(store.get(&private).unwrap(), "internal-test-value");
            store.delete(&private).unwrap();
            assert!(matches!(
                store.get(&private),
                Err(SecretError::NotFound { .. })
            ));
        }

        // Restore process state so no parallel/later test inherits the redirect.
        std::env::remove_var("CAR_SECRETS_FILE_DIR");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn every_parslee_auth_slot_is_private_to_the_dedicated_auth_surface() {
        for key in [
            PARSLEE_ACCESS_TOKEN_KEY,
            PARSLEE_REFRESH_TOKEN_KEY,
            PARSLEE_EXPIRES_AT_KEY,
            PARSLEE_API_BASE_KEY,
            PARSLEE_ACCOUNTS_KEY,
            "PARSLEE_TOKENS_account-1",
            PARSLEE_ACTIVE_ACCOUNT_ID_KEY,
            PARSLEE_AUTH_GENERATION_KEY,
            PARSLEE_AUTH_COMPLETION_KEY,
            PARSLEE_AUTH_STATE_V2_KEY,
        ] {
            assert!(
                is_daemon_private_secret(DEFAULT_SERVICE, key),
                "{key} must be unreachable through generic secret surfaces"
            );
            assert!(
                !is_daemon_private_secret("other-service", key),
                "reservation must remain scoped to the CAR service"
            );
        }

        assert!(!is_daemon_private_secret(
            DEFAULT_SERVICE,
            "OPENROUTER_API_KEY"
        ));
        for key in [
            format!("{PARSLEE_AUTH_STATE_V2_KEY}#chunk0"),
            format!("{PARSLEE_AUTH_STATE_V2_KEY}#chunkv2#nonce-1#0"),
            format!("{OPENROUTER_OAUTH_KEY}#chunk17"),
            format!("{OPENROUTER_OAUTH_KEY}#chunkv2#nonce-2#3"),
        ] {
            assert!(
                is_daemon_private_secret(DEFAULT_SERVICE, &key),
                "{key} is derived from a daemon-private root"
            );
            assert!(!is_daemon_private_secret("other-service", &key));
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn security_cli_output_large_helper() {
        if std::env::var_os("CAR_SECURITY_OUTPUT_HELPER").is_none() {
            return;
        }
        use std::io::Write;
        let payload = vec![b'x'; 128 * 1024];
        std::io::stdout().write_all(&payload).unwrap();
        std::io::stdout().flush().unwrap();
        std::io::stderr().write_all(&payload).unwrap();
        std::io::stderr().flush().unwrap();
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn security_cli_output_drains_large_stdout_and_stderr() {
        let mut command = std::process::Command::new(std::env::current_exe().unwrap());
        command
            .args([
                "--exact",
                "tests::security_cli_output_large_helper",
                "--nocapture",
            ])
            .env("CAR_SECURITY_OUTPUT_HELPER", "1");

        let output = SecurityCliExecutor::new(std::time::Duration::from_secs(15))
            .output(command, "test", || Ok(()))
            .unwrap();

        assert!(output.success, "{output:?}");
        assert!(output.stdout.len() >= 128 * 1024);
        assert!(output.stderr.len() >= 128 * 1024);
    }

    #[cfg(target_os = "macos")]
    pub(super) struct FakeSecurityCli {
        outputs:
            std::cell::RefCell<std::collections::VecDeque<Result<SecurityCliOutput, SecretError>>>,
        calls: std::cell::RefCell<Vec<Vec<String>>>,
    }

    #[cfg(target_os = "macos")]
    impl FakeSecurityCli {
        pub(super) fn new(outputs: Vec<Result<SecurityCliOutput, SecretError>>) -> Self {
            Self {
                outputs: std::cell::RefCell::new(outputs.into()),
                calls: std::cell::RefCell::new(Vec::new()),
            }
        }

        pub(super) fn calls(&self) -> Vec<Vec<String>> {
            self.calls.borrow().clone()
        }
    }

    #[cfg(target_os = "macos")]
    impl SecurityCli for FakeSecurityCli {
        fn output(&self, args: &[&str]) -> Result<SecurityCliOutput, SecretError> {
            self.calls
                .borrow_mut()
                .push(args.iter().map(|arg| (*arg).to_string()).collect());
            self.outputs
                .borrow_mut()
                .pop_front()
                .expect("missing fake security output")
        }
    }

    #[cfg(target_os = "macos")]
    pub(super) fn security_output(
        code: i32,
        stdout: impl Into<Vec<u8>>,
        stderr: impl Into<Vec<u8>>,
    ) -> Result<SecurityCliOutput, SecretError> {
        Ok(SecurityCliOutput {
            success: code == 0,
            code: Some(code),
            stdout: stdout.into(),
            stderr: stderr.into(),
        })
    }

    #[cfg(target_os = "macos")]
    fn args(values: &[&str]) -> Vec<String> {
        values.iter().map(|value| (*value).to_string()).collect()
    }

    /// A readable keychain is not necessarily writable from a non-interactive
    /// process. Availability must preserve the real write signal from car#1158.
    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_reports_unavailable_when_reads_succeed_but_writes_are_denied() {
        struct ReadableButWriteDeniedCli;

        impl SecurityCli for ReadableButWriteDeniedCli {
            fn output(&self, args: &[&str]) -> Result<SecurityCliOutput, SecretError> {
                match args.first().copied() {
                    Some("find-generic-password") => security_output(0, "", ""),
                    Some("add-generic-password") => security_output(
                        152,
                        "",
                        "security: SecKeychainItemCreateFromContent: User interaction is not allowed.",
                    ),
                    other => panic!("unexpected security command: {other:?}"),
                }
            }
        }

        let check = mac_availability_via_security_cli_with(&ReadableButWriteDeniedCli);

        assert!(!check.available);
        let reason = check
            .reason
            .expect("write-denied probe must carry a reason");
        assert!(
            reason.contains("User interaction is not allowed"),
            "reason should carry the write error, got {reason:?}"
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn availability_probe_reads_then_writes_the_retained_sentinel() {
        let cli = FakeSecurityCli::new(vec![
            security_output(SECURITY_ERR_SEC_ITEM_NOT_FOUND, "", ""),
            security_output(0, "", ""),
        ]);

        let check = mac_availability_via_security_cli_with(&cli);

        assert!(check.available, "{:?}", check.reason);
        assert_eq!(
            cli.calls(),
            vec![
                args(&[
                    "find-generic-password",
                    "-s",
                    "car-internal",
                    "-a",
                    "__availability_probe__",
                ]),
                args(&[
                    "add-generic-password",
                    "-U",
                    "-A",
                    "-s",
                    "car-internal",
                    "-a",
                    "__availability_probe__",
                    "-w",
                    "car-availability-probe",
                ]),
            ]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn keychain_status_requires_unlocked_readable_and_requested_access() {
        assert_eq!(
            MacKeychainAccess::for_security_args(&["find-generic-password"]),
            MacKeychainAccess::Read
        );
        assert_eq!(
            MacKeychainAccess::for_security_args(&["future-security-command"]),
            MacKeychainAccess::Write,
            "unknown helper operations must fail closed to write access"
        );
        assert!(mac_keychain_status_allows(
            KEYCHAIN_UNLOCKED | KEYCHAIN_READABLE,
            MacKeychainAccess::Read
        ));
        assert!(!mac_keychain_status_allows(
            KEYCHAIN_READABLE | KEYCHAIN_WRITABLE,
            MacKeychainAccess::Read
        ));
        let locked = mac_keychain_preflight_status(
            KEYCHAIN_READABLE | KEYCHAIN_WRITABLE,
            MacKeychainAccess::Read,
        )
        .unwrap_err();
        assert!(matches!(locked, SecretError::Unavailable(reason) if reason.contains("locked")));
        assert!(!mac_keychain_status_allows(
            KEYCHAIN_UNLOCKED | KEYCHAIN_WRITABLE,
            MacKeychainAccess::Read
        ));
        assert!(!mac_keychain_status_allows(
            KEYCHAIN_UNLOCKED | KEYCHAIN_READABLE,
            MacKeychainAccess::Write
        ));
        assert!(mac_keychain_status_allows(
            KEYCHAIN_UNLOCKED | KEYCHAIN_READABLE | KEYCHAIN_WRITABLE,
            MacKeychainAccess::Write
        ));
    }

    /// A locked-keychain result must be terminal before a child exists. The
    /// marker is the spawn witness: if command execution moves above the
    /// preflight, this test leaves a file and fails.
    #[cfg(target_os = "macos")]
    #[test]
    fn locked_keychain_fails_before_security_child_spawn() {
        let dir = tempfile::tempdir().unwrap();
        let marker = dir.path().join("security-child-spawned");
        let mut command = std::process::Command::new("/bin/sh");
        command
            .args(["-c", r#"printf spawned > "$1""#, "security-probe"])
            .arg(&marker);

        let result = SecurityCliExecutor::new(std::time::Duration::from_secs(15)).output(
            command,
            "find-generic-password",
            || {
                Err(SecretError::Unavailable(
                    "macOS keychain is locked".to_string(),
                ))
            },
        );

        assert!(matches!(result, Err(SecretError::Unavailable(_))));
        assert!(
            !marker.exists(),
            "security child ran before keychain preflight"
        );
    }

    /// A helper completing before the caller deadline returns its natural result.
    #[cfg(target_os = "macos")]
    #[test]
    fn security_child_returns_naturally_without_a_car_kill() {
        let mut command = std::process::Command::new("/bin/sh");
        command.args(["-c", "sleep 0.05; printf natural-exit"]);

        let output = SecurityCliExecutor::new(std::time::Duration::from_secs(15))
            .output(command, "test", || Ok(()))
            .unwrap();

        assert!(output.success);
        assert_eq!(output.stdout, b"natural-exit");
    }

    /// Status success cannot rule out a later item-ACL prompt. Keep that child
    /// owned after timeout, reject overlapping retries, then recover on exit.
    #[cfg(target_os = "macos")]
    #[test]
    fn stalled_security_helper_is_bounded_owned_and_not_duplicated() {
        use std::sync::atomic::Ordering;
        use std::time::{Duration, Instant};
        let dir = tempfile::tempdir().unwrap();
        let marker = dir.path().join("started");
        let release = dir.path().join("release");
        let terminated = dir.path().join("terminated");
        let exited = dir.path().join("exited");
        let executor = SecurityCliExecutor::new(Duration::from_millis(100));
        let mut command = std::process::Command::new("/bin/sh");
        command
            .args([
                "-c",
                r#"
            trap 'printf signal > "$3"; exit 3' TERM INT HUP
            printf started >> "$1"
            while [ ! -f "$2" ]; do sleep 0.01; done
            printf natural-exit > "$4"
        "#,
                "fake-security",
            ])
            .arg(&marker)
            .arg(&release)
            .arg(&terminated)
            .arg(&exited);
        // Release the fixture on panic as well: never leave a fake child stuck.
        struct Release(std::path::PathBuf);
        impl Drop for Release {
            fn drop(&mut self) {
                let _ = std::fs::write(&self.0, b"release");
            }
        }
        let cleanup = Release(release.clone());
        let started = Instant::now();
        let first = executor.output(command, "find-generic-password", || {
            mac_keychain_preflight_status(
                KEYCHAIN_UNLOCKED | KEYCHAIN_READABLE,
                MacKeychainAccess::Read,
            )
        });
        assert!(
            matches!(first, Err(SecretError::Unavailable(message)) if message.contains("pending"))
        );
        assert!(started.elapsed() < Duration::from_secs(2));
        // The retry would append a second marker if it were ever spawned.
        let mut retry = std::process::Command::new("/bin/sh");
        retry
            .args(["-c", r#"printf duplicate >> "$1""#, "fake-security"])
            .arg(&marker);
        let started = Instant::now();
        let second = executor.output(retry, "find-generic-password", || Ok(()));
        assert!(
            matches!(second, Err(SecretError::Unavailable(message)) if message.contains("no additional helper"))
        );
        assert!(started.elapsed() < Duration::from_secs(2));
        drop(cleanup);
        let deadline = Instant::now() + Duration::from_secs(5);
        while executor.in_flight.load(Ordering::Acquire) {
            assert!(
                Instant::now() < deadline,
                "natural exit must clear owned flight"
            );
            std::thread::sleep(Duration::from_millis(5));
        }
        assert_eq!(std::fs::read_to_string(marker).unwrap(), "started");
        assert_eq!(std::fs::read_to_string(exited).unwrap(), "natural-exit");
        assert!(
            !terminated.exists(),
            "helper must never receive a termination signal"
        );
        let mut recovered = std::process::Command::new("/bin/sh");
        recovered.args(["-c", "printf recovered"]);
        let output = executor
            .output(recovered, "find-generic-password", || Ok(()))
            .unwrap();
        assert!(output.success);
        assert_eq!(output.stdout, b"recovered");
    }

    #[cfg(target_os = "macos")]
    fn assert_access_denied_contains(err: SecretError, expected: &str) {
        match err {
            SecretError::AccessDenied { message } => assert!(
                message.contains(expected),
                "expected access-denied error to contain {expected:?}, got {message:?}"
            ),
            other => panic!("expected AccessDenied, got {:?}", other),
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_security_errors_are_typed_for_recovery() {
        assert!(matches!(
            classify_security_error(-128, "user canceled"),
            SecretError::UserCancelled { .. }
        ));
        assert!(matches!(
            classify_security_error(-25293, "authorization denied"),
            SecretError::AccessDenied { .. }
        ));
    }

    #[cfg(target_os = "macos")]
    struct IsolatedKeychainFixture {
        _temp: tempfile::TempDir,
        proof_root: std::path::PathBuf,
        valid_path: std::path::PathBuf,
        symlink_path: std::path::PathBuf,
        outside_path: std::path::PathBuf,
        public_path: std::path::PathBuf,
        directory_path: std::path::PathBuf,
        public_root: std::path::PathBuf,
    }

    #[cfg(target_os = "macos")]
    impl IsolatedKeychainFixture {
        fn new() -> Self {
            use std::os::unix::fs::{symlink, PermissionsExt};

            let temp = tempfile::tempdir().unwrap();
            let proof_root = temp.path().join("proof");
            std::fs::create_dir(&proof_root).unwrap();
            std::fs::set_permissions(&proof_root, std::fs::Permissions::from_mode(0o700)).unwrap();

            let valid_path = proof_root.join("valid.keychain-db");
            std::fs::write(&valid_path, b"keychain fixture").unwrap();
            std::fs::set_permissions(&valid_path, std::fs::Permissions::from_mode(0o600)).unwrap();

            let symlink_path = proof_root.join("linked.keychain-db");
            symlink(&valid_path, &symlink_path).unwrap();

            let outside_path = temp.path().join("outside.keychain-db");
            std::fs::write(&outside_path, b"outside fixture").unwrap();
            std::fs::set_permissions(&outside_path, std::fs::Permissions::from_mode(0o600))
                .unwrap();

            let public_path = proof_root.join("public.keychain-db");
            std::fs::write(&public_path, b"public fixture").unwrap();
            std::fs::set_permissions(&public_path, std::fs::Permissions::from_mode(0o644)).unwrap();

            let directory_path = proof_root.join("directory.keychain-db");
            std::fs::create_dir(&directory_path).unwrap();

            let public_root = temp.path().join("public-proof");
            std::fs::create_dir(&public_root).unwrap();
            std::fs::set_permissions(&public_root, std::fs::Permissions::from_mode(0o755)).unwrap();

            Self {
                _temp: temp,
                proof_root,
                valid_path,
                symlink_path,
                outside_path,
                public_path,
                directory_path,
                public_root,
            }
        }

        fn proof_root(&self) -> &std::path::Path {
            &self.proof_root
        }

        fn valid_path(&self) -> &std::path::Path {
            &self.valid_path
        }

        fn symlink_path(&self) -> &std::path::Path {
            &self.symlink_path
        }

        fn outside_path(&self) -> &std::path::Path {
            &self.outside_path
        }

        fn public_path(&self) -> &std::path::Path {
            &self.public_path
        }

        fn directory_path(&self) -> &std::path::Path {
            &self.directory_path
        }

        fn public_root(&self) -> &std::path::Path {
            &self.public_root
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn isolated_keychain_must_be_absolute_private_regular_owned_and_under_proof_root() {
        let fixture = IsolatedKeychainFixture::new();
        assert!(validate_keychain_path(fixture.valid_path(), fixture.proof_root()).is_ok());
        assert!(validate_keychain_path(
            std::path::Path::new("relative.keychain-db"),
            fixture.proof_root()
        )
        .is_err());
        assert!(validate_keychain_path(fixture.symlink_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.outside_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.public_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.directory_path(), fixture.proof_root()).is_err());
        assert!(validate_keychain_path(fixture.valid_path(), fixture.public_root()).is_err());
    }

    #[test]
    fn secret_store_activity_counts_only_aggregate_public_operation_attempts() {
        let _guard = lock_store();
        let dir = tempfile::tempdir().unwrap();
        std::env::set_var("CAR_SECRETS_FILE_DIR", dir.path());
        let before = secret_store_activity();
        let store = SecretStore::new();
        let secret = SecretRef::new("activity-test", "credential");

        assert!(store.availability().available);
        store.put(&secret, "sensitive-value").unwrap();
        let _ = store.get(&secret).unwrap();
        let _ = store.status(&secret).unwrap();
        store.publish(&secret, "replacement-value").unwrap();
        store.delete(&secret).unwrap();

        let after = secret_store_activity();
        assert_eq!(after.get_attempts - before.get_attempts, 1);
        assert_eq!(after.status_attempts - before.status_attempts, 1);
        assert_eq!(
            after.availability_attempts - before.availability_attempts,
            1
        );
        assert_eq!(after.write_attempts - before.write_attempts, 2);
        assert_eq!(after.delete_attempts - before.delete_attempts, 1);

        let encoded = serde_json::to_string(&after).unwrap();
        assert!(!encoded.contains("activity-test"));
        assert!(!encoded.contains("credential"));
        assert!(!encoded.contains("sensitive-value"));
        assert!(!encoded.contains(dir.path().to_string_lossy().as_ref()));
        std::env::remove_var("CAR_SECRETS_FILE_DIR");
    }

    /// The default run uses only the isolated backend. Provisioned native
    /// Keychain coverage is explicit and serial:
    ///
    /// `env -u CAR_SECRETS_FILE_DIR CAR_TEST_NATIVE_KEYCHAIN=1 cargo test -p car-secrets tests::roundtrip_string -- --exact --nocapture --test-threads=1`
    ///
    /// That lane fails loudly when the Keychain probe is unavailable, uses a
    /// unique service, and asserts cleanup. Native helper calls retain their
    /// production deadlines.
    #[test]
    fn roundtrip_string() {
        #[cfg(target_os = "macos")]
        if std::env::var_os(NATIVE_KEYCHAIN_LANE).is_some() {
            run_native_keychain_lane();
            return;
        }

        let fixture = IsolatedStoreFixture::new();
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "roundtrip");
        store.put(&r, "hello world").unwrap();
        assert_eq!(store.get(&r).unwrap(), "hello world");
        assert!(store.status(&r).unwrap().exists);
        store.delete(&r).unwrap();
        assert!(!store.status(&r).unwrap().exists);
    }

    #[test]
    fn env_resolution_returns_before_any_secret_store_read() {
        const NAME: &str = "CAR_SECRETS_ENV_FIRST_TEST";
        let _fixture = IsolatedStoreFixture::new();
        let _env = ClearedEnv::new(NAME);
        std::env::set_var(NAME, "from-environment");
        let before = secret_store_activity();

        assert_eq!(
            resolve_env_or_keychain(NAME),
            Some("from-environment".to_string())
        );

        let after = secret_store_activity();
        assert_eq!(after.get_attempts, before.get_attempts);
        assert_eq!(after.availability_attempts, before.availability_attempts);
    }

    #[test]
    fn env_resolution_reads_the_keychain_without_an_availability_write() {
        let fixture = IsolatedStoreFixture::new();
        let _env = ClearedEnv::new("CAR_SECRETS_RESOLUTION_READ_ONLY_TEST");
        let store = fixture.store();
        let reference = SecretRef::with_default_service("CAR_SECRETS_RESOLUTION_READ_ONLY_TEST");
        store.put(&reference, "from-keychain").unwrap();

        let before = secret_store_activity();
        assert_eq!(
            resolve_env_or_keychain("CAR_SECRETS_RESOLUTION_READ_ONLY_TEST"),
            Some("from-keychain".to_string())
        );
        let after = secret_store_activity();

        assert_eq!(after.get_attempts, before.get_attempts + 1);
        assert_eq!(after.availability_attempts, before.availability_attempts);
        assert_eq!(after.write_attempts, before.write_attempts);
        assert_eq!(after.delete_attempts, before.delete_attempts);
        store.delete(&reference).unwrap();
    }

    #[test]
    fn roundtrip_string_with_trailing_newline() {
        let fixture = IsolatedStoreFixture::new();
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "roundtrip-newline");
        let value = "abc\n";
        store.put(&r, value).unwrap();
        assert_eq!(store.get(&r).unwrap(), value);
        store.delete(&r).unwrap();
    }

    #[test]
    fn get_missing_returns_not_found() {
        let fixture = IsolatedStoreFixture::new();
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "never-written");
        match store.get(&r) {
            Err(SecretError::NotFound { .. }) => (),
            other => panic!("expected NotFound, got {:?}", other),
        }
    }

    #[test]
    fn delete_missing_is_idempotent() {
        let fixture = IsolatedStoreFixture::new();
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "missing");
        store.delete(&r).unwrap();
        store.delete(&r).unwrap();
    }

    #[test]
    fn json_roundtrip() {
        let fixture = IsolatedStoreFixture::new();
        #[derive(Serialize, Deserialize, PartialEq, Debug)]
        struct Session {
            cookies: Vec<String>,
            expires_at: i64,
        }
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "session");
        let s = Session {
            cookies: vec!["a=1".into(), "b=2".into()],
            expires_at: 1_700_000_000,
        };
        store.put_json(&r, &s).unwrap();
        let back: Session = store.get_json(&r).unwrap();
        assert_eq!(back, s);
        store.delete(&r).unwrap();
    }

    #[test]
    fn status_no_leak() {
        let fixture = IsolatedStoreFixture::new();
        let store = fixture.store();
        let r = SecretRef::new("isolated-contract", "status");
        store.put(&r, "secret-payload").unwrap();
        let st = store.status(&r).unwrap();
        let encoded = serde_json::to_string(&st).unwrap();
        assert!(!encoded.contains("secret-payload"));
        store.delete(&r).unwrap();
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_uses_security_cli_and_maps_success() {
        let cli = FakeSecurityCli::new(vec![security_output(
            0,
            b"keychain: \"/Users/example/Library/Keychains/login.keychain-db\"\n",
            b"password: \"secret\"\n",
        )]);
        let r = SecretRef::new("svc", "key");

        assert_eq!(mac_get_via_security_cli_with(&r, &cli).unwrap(), "secret");
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "svc",
                "-a",
                "key",
                "-g"
            ])]
        );
    }

    /// A successful read remains one find call with no delete, write, or
    /// partition rewrite. Waiting for the helper naturally must not revive the
    /// old ACL-repair mutation.
    #[cfg(target_os = "macos")]
    #[test]
    fn successful_read_preserves_the_item_and_persisted_grant() {
        let cli = FakeSecurityCli::new(vec![security_output(
            0,
            b"keychain: isolated-test.keychain-db\n",
            b"password: \"secret\"\n",
        )]);
        let r = SecretRef::new("car-test-0o9-prompt-persistence", "credential");

        assert_eq!(mac_get_via_security_cli_with(&r, &cli).unwrap(), "secret");
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "car-test-0o9-prompt-persistence",
                "-a",
                "credential",
                "-g",
            ])],
            "an approved read must never rewrite or recreate the item"
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_decodes_hex_password_output_with_trailing_newline() {
        let cli = FakeSecurityCli::new(vec![security_output(
            0,
            b"keychain: \"/Users/example/Library/Keychains/login.keychain-db\"\n",
            b"password: 0x6162630A  \"abc\\012\"\n",
        )]);
        let r = SecretRef::new("svc", "key");

        assert_eq!(mac_get_via_security_cli_with(&r, &cli).unwrap(), "abc\n");
        assert_eq!(
            cli.calls(),
            vec![args(&[
                "find-generic-password",
                "-s",
                "svc",
                "-a",
                "key",
                "-g"
            ])]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_get_maps_not_found_and_access_denied_without_fallback() {
        let r = SecretRef::new("svc", "missing");
        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);

        match mac_get_via_security_cli_with(&r, &cli) {
            Err(SecretError::NotFound { service, key }) => {
                assert_eq!(service, "svc");
                assert_eq!(key, "missing");
            }
            other => panic!("expected NotFound, got {:?}", other),
        }
        assert_eq!(cli.calls().len(), 1);

        let cli = FakeSecurityCli::new(vec![security_output(
            51,
            b"",
            b"User interaction is not allowed.\n",
        )]);
        let err = mac_get_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "User interaction is not allowed.");
        assert_eq!(cli.calls().len(), 1);
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_status_uses_security_cli_and_maps_results() {
        let r = SecretRef::new("svc", "key");
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        let status = mac_status_via_security_cli_with(&r, &cli).unwrap();
        assert!(status.exists);
        assert_eq!(
            cli.calls(),
            vec![args(&["find-generic-password", "-s", "svc", "-a", "key"])]
        );

        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);
        assert!(!mac_status_via_security_cli_with(&r, &cli).unwrap().exists);

        let cli = FakeSecurityCli::new(vec![security_output(128, b"", b"auth denied\n")]);
        let err = mac_status_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "auth denied");
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_put_surfaces_add_failure_as_access_denied() {
        let cli = FakeSecurityCli::new(vec![security_output(
            51,
            b"",
            b"User interaction is not allowed.\n",
        )]);

        let err =
            mac_write_via_security_cli("car-test-0o9-write", "key", "secret", &cli).unwrap_err();
        assert_access_denied_contains(err, "User interaction is not allowed.");
        assert_eq!(
            cli.calls().len(),
            1,
            "a failed write must not trigger a delete"
        );
    }

    /// The regression in `Parslee-ai/car#1274`: an ordinary write must not
    /// delete first. A delete needs the user's authorization even though `-A`
    /// already granted every application read access, so an unconditional
    /// pre-delete drew a dialog on every token refresh — every ~15 minutes,
    /// forever, and on an unattended run nobody to answer it.
    #[cfg(target_os = "macos")]
    #[test]
    fn mac_put_does_not_pre_delete_and_therefore_cannot_prompt() {
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        mac_put_via_security_cli_with("car-test-0o9-update-persistence", "key", "secret", &cli)
            .unwrap();

        assert_eq!(
            cli.calls(),
            vec![args(&[
                "add-generic-password",
                "-U",
                "-A",
                "-s",
                "car-test-0o9-update-persistence",
                "-a",
                "key",
                "-w",
                "secret",
            ])],
            "an ordinary write must issue exactly one call, and not a delete"
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_publish_updates_in_place_without_a_pre_delete_gap() {
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        mac_publish_via_security_cli_with("svc", "key", "secret", &cli).unwrap();

        assert_eq!(
            cli.calls(),
            vec![args(&[
                "add-generic-password",
                "-U",
                "-A",
                "-s",
                "svc",
                "-a",
                "key",
                "-w",
                "secret",
            ])]
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn mac_delete_uses_security_cli_and_maps_results() {
        let r = SecretRef::new("svc", "key");
        let cli = FakeSecurityCli::new(vec![security_output(0, b"", b"")]);

        mac_delete_via_security_cli_with(&r, &cli).unwrap();
        assert_eq!(
            cli.calls(),
            vec![args(&["delete-generic-password", "-s", "svc", "-a", "key"])]
        );

        let cli = FakeSecurityCli::new(vec![security_output(
            SECURITY_ERR_SEC_ITEM_NOT_FOUND,
            b"",
            b"The specified item could not be found in the keychain.\n",
        )]);
        mac_delete_via_security_cli_with(&r, &cli).unwrap();

        let cli = FakeSecurityCli::new(vec![security_output(128, b"", b"auth denied\n")]);
        let err = mac_delete_via_security_cli_with(&r, &cli).unwrap_err();
        assert_access_denied_contains(err, "auth denied");
    }
}