rigg_core/

store.rs

//! Project-scoped resource file store and sync-state classification.
//!
//! Layout inside a project directory:
//!
//! ```text
//! projects/<name>/
//!   project.yaml
//!   envs/<env>/
//!     search/<kind-dir>/<resource-stem>.json
//!     foundry/<kind-dir>/<resource-stem>.json
//! ```
//!
//! Each environment gets its own complete resource tree. The **file stem**
//! (kind dir + filename) is the resource's *logical* identity — the
//! correlation across environments. The **`name` field inside the file** is
//! the *physical* Azure name for that environment; by default stem == name,
//! but they may diverge when a resource is renamed in one environment (see
//! [`Store::list`] / [`Store::locate`]).
//!
//! Files are written via [`crate::normalize::normalize_for_disk`] and long
//! text fields are extracted to Markdown sidecars ([`crate::sidecar`]).
//! Baselines (`.rigg/<env>/<project>/state.json`) hold the checksum of each
//! resource at last sync, enabling local/remote/conflict classification.

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

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

use crate::normalize::{
    format_json, normalize_for_compare, normalize_for_disk, normalize_for_push,
};
use crate::resources::traits::{ResourceKind, ResourceRef, validate_resource_name};
use crate::service::ServiceDomain;
use crate::sidecar::{self, SidecarError};
use crate::workspace::{ENVS_DIR, Project, Workspace};

#[derive(Debug, Error)]
pub enum StoreError {
    #[error("failed to read {path}: {source}")]
    Io {
        path: PathBuf,
        source: std::io::Error,
    },
    #[error("invalid JSON in {path}: {source}")]
    Parse {
        path: PathBuf,
        source: serde_json::Error,
    },
    #[error(transparent)]
    Sidecar(#[from] SidecarError),
    #[error("invalid resource name in {path}: {message}")]
    BadName { path: PathBuf, message: String },
    #[error(
        "duplicate physical name '{name}': both {first} and {second} define a resource named '{name}' — physical (Azure) names must be unique within a kind"
    )]
    DuplicatePhysicalName {
        name: String,
        first: PathBuf,
        second: PathBuf,
    },
    #[error(
        "resource {reference} is defined in both project '{first}' and project '{second}' — a resource must belong to exactly one project"
    )]
    DuplicateOwnership {
        reference: String,
        first: String,
        second: String,
    },
    #[error(
        "cannot create '{path}': stem is already used by a different resource (existing physical name '{existing_name}', new '{new_name}')"
    )]
    StemOccupiedByDifferentResource {
        path: PathBuf,
        existing_name: String,
        new_name: String,
    },
}

type Result<T> = std::result::Result<T, StoreError>;

/// File store for one project, rooted at one environment's tree.
pub struct Store<'w> {
    project: &'w Project,
    env: String,
}

impl<'w> Store<'w> {
    pub fn new(project: &'w Project, env: &str) -> Self {
        Store {
            project,
            env: env.to_string(),
        }
    }

    pub fn project(&self) -> &Project {
        self.project
    }

    pub fn env(&self) -> &str {
        &self.env
    }

    /// List the environments a project participates in: the sorted names of
    /// `<project>/envs/*` subdirectories. A project with no env dirs yet
    /// participates in none (scaffold/adopt/pull materializes them lazily).
    pub fn envs_of(project: &Project) -> Vec<String> {
        let dir = project.dir.join(ENVS_DIR);
        let mut envs: Vec<String> = std::fs::read_dir(&dir)
            .map(|entries| {
                entries
                    .filter_map(|e| e.ok())
                    .map(|e| e.path())
                    .filter(|p| p.is_dir())
                    .filter_map(|p| p.file_name().map(|n| n.to_string_lossy().into_owned()))
                    .collect()
            })
            .unwrap_or_default();
        envs.sort();
        envs
    }

    /// Root of this store's environment tree: `<project>/envs/<env>/`.
    fn root(&self) -> PathBuf {
        self.project.dir.join(ENVS_DIR).join(&self.env)
    }

    fn domain_dir(domain: ServiceDomain) -> &'static str {
        match domain {
            ServiceDomain::Search => "search",
            ServiceDomain::Foundry => "foundry",
        }
    }

    fn kind_dir(&self, kind: ResourceKind) -> PathBuf {
        self.root()
            .join(Self::domain_dir(kind.domain()))
            .join(kind.directory_name())
    }

    /// Absolute path for a NEW resource file (used on create — the physical
    /// name becomes the filename). Existing resources may live at a
    /// different path when their file stem diverged from the physical name;
    /// use [`Store::locate`] to find those.
    pub fn path_for(&self, r: &ResourceRef) -> PathBuf {
        self.kind_dir(r.kind).join(format!("{}.json", r.name))
    }

    /// Find the file in this store whose physical name (`name` field, or the
    /// file stem when absent) equals `r.name`. Scans the kind directory —
    /// small dirs, correctness over micro-optimization.
    pub fn locate(&self, r: &ResourceRef) -> Result<Option<PathBuf>> {
        let dir = self.kind_dir(r.kind);
        if !dir.is_dir() {
            return Ok(None);
        }
        // Fast path: stem == physical name (the common case).
        let fast = dir.join(format!("{}.json", r.name));
        if fast.is_file() && physical_name(&fast, &r.name)? == r.name {
            return Ok(Some(fast));
        }
        let mut entries: Vec<PathBuf> = std::fs::read_dir(&dir)
            .map_err(|source| StoreError::Io {
                path: dir.clone(),
                source,
            })?
            .filter_map(|e| e.ok())
            .map(|e| e.path())
            .filter(|p| p.extension().is_some_and(|e| e == "json"))
            .collect();
        entries.sort();
        for path in entries {
            if path == fast {
                continue; // already checked above
            }
            let stem = path
                .file_stem()
                .map(|s| s.to_string_lossy().into_owned())
                .unwrap_or_default();
            if physical_name(&path, &stem)? == r.name {
                return Ok(Some(path));
            }
        }
        Ok(None)
    }

    /// Path for a resource being CREATED: `<physical name>.json`, or — when
    /// that stem is already occupied by a DIFFERENT resource (a renamed one
    /// whose stem no longer matches its `name` field) — the first free
    /// numbered stem (`<name>-2.json`, `<name>-3.json`, …). The create path
    /// never points at an existing file, so creating can never overwrite a
    /// renamed resource.
    fn create_path_for(&self, r: &ResourceRef) -> PathBuf {
        let dir = self.kind_dir(r.kind);
        let base = dir.join(format!("{}.json", r.name));
        if !base.exists() {
            return base;
        }
        for i in 2u64.. {
            let candidate = dir.join(format!("{}-{i}.json", r.name));
            if !candidate.exists() {
                return candidate;
            }
        }
        unreachable!("some numbered stem is always free")
    }

    /// Scan this store's environment tree for resource files, keyed by
    /// PHYSICAL name (the file's `name` field, falling back to its stem).
    ///
    /// A file with invalid JSON is a HARD error (deliberately): sync
    /// operations (push/pull/prune/ownership checks) build their world view
    /// from this listing, and silently skipping a broken file would let them
    /// act on a partial view — e.g. pruning a resource that still exists
    /// locally. Fail loud and name the file instead.
    pub fn list(&self) -> Result<Vec<(ResourceRef, PathBuf)>> {
        let mut out = Vec::new();
        for kind in ResourceKind::all() {
            let dir = self.kind_dir(*kind);
            if !dir.is_dir() {
                continue;
            }
            let mut entries: Vec<PathBuf> = std::fs::read_dir(&dir)
                .map_err(|source| StoreError::Io {
                    path: dir.clone(),
                    source,
                })?
                .filter_map(|e| e.ok())
                .map(|e| e.path())
                .filter(|p| p.extension().is_some_and(|e| e == "json"))
                .collect();
            entries.sort();
            let mut seen: BTreeMap<String, PathBuf> = BTreeMap::new();
            for path in entries {
                let stem = path
                    .file_stem()
                    .map(|s| s.to_string_lossy().into_owned())
                    .unwrap_or_default();
                let name = physical_name(&path, &stem)?;
                validate_resource_name(&name).map_err(|e| StoreError::BadName {
                    path: path.clone(),
                    message: e.to_string(),
                })?;
                if let Some(first) = seen.get(&name) {
                    return Err(StoreError::DuplicatePhysicalName {
                        name,
                        first: first.clone(),
                        second: path,
                    });
                }
                seen.insert(name.clone(), path.clone());
                out.push((ResourceRef::new(*kind, name), path));
            }
        }
        Ok(out)
    }

    /// Read a resource file with sidecars inlined. Locates the file by
    /// physical name; when nothing matches, the error keeps the plain `Io`
    /// not-found shape callers expect (pointing at the stem-guessed path).
    /// It never falls through to reading a file whose physical name differs
    /// from `r.name` (a renamed resource occupying the stem).
    pub fn read(&self, r: &ResourceRef) -> Result<Value> {
        match self.locate(r)? {
            Some(path) => self.read_path(&path),
            None => Err(StoreError::Io {
                path: self.path_for(r),
                source: std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    format!("no resource with physical name '{}'", r.name),
                ),
            }),
        }
    }

    /// Read any resource file (must belong to this project) with sidecars inlined.
    pub fn read_path(&self, path: &Path) -> Result<Value> {
        let text = std::fs::read_to_string(path).map_err(|source| StoreError::Io {
            path: path.to_path_buf(),
            source,
        })?;
        let mut value: Value = serde_json::from_str(&text).map_err(|source| StoreError::Parse {
            path: path.to_path_buf(),
            source,
        })?;
        sidecar::inline_sidecars(path, &mut value)?;
        Ok(value)
    }

    /// Write a resource: normalize for disk, extract sidecars, write only if
    /// the semantic content changed. Returns true if the file was (re)written.
    ///
    /// Updates the located file when one exists (by physical name). When
    /// none exists (create), the target stem is DISAMBIGUATED, never stolen:
    /// if `<name>.json` is already occupied by a renamed resource, the new
    /// file lands at `<name>-2.json` (then `-3`, …). This keeps sync
    /// operations (pull/adopt capture cloud reality mid-run) robust instead
    /// of failing, while `locate` keeps lookups correct regardless of stem.
    pub fn write(&self, r: &ResourceRef, value: &Value) -> Result<bool> {
        self.write_inner(r, value, CarryOver::Yes)
    }

    /// Like [`Store::write`], but writes the document EXACTLY as given: no
    /// write-only carry-over and no `x-rigg-*` carry-over from the file being
    /// replaced.
    ///
    /// This is what `rigg promote` needs. Its merged document already carries
    /// the target environment's pins and annotations deliberately, and the
    /// write-only fields are precisely what it translated (a data source's
    /// `credentials.connectionString` is rewritten to point at the target's
    /// storage account) — carrying the old file's values back over would
    /// silently undo the translation and promote would never converge.
    pub fn write_exact(&self, r: &ResourceRef, value: &Value) -> Result<bool> {
        self.write_inner(r, value, CarryOver::No)
    }

    fn write_inner(&self, r: &ResourceRef, value: &Value, carry: CarryOver) -> Result<bool> {
        // Defense in depth: a physical name containing '/', '\' or '..' would
        // otherwise build a path escaping the kind directory — and land where
        // `list()`'s non-recursive scan never sees it.
        validate_resource_name(&r.name).map_err(|e| StoreError::BadName {
            path: self.create_path_for(r),
            message: e.to_string(),
        })?;
        let path = match self.locate(r)? {
            Some(existing) => existing,
            None => self.create_path_for(r),
        };
        let mut normalized = normalize_for_disk(r.kind, value);

        // Preserve any x-rigg-* annotations the user added locally: they are
        // Rigg-local and never come back from Azure.
        if path.is_file()
            && let Ok(existing) = self.read_path(&path)
        {
            if carry == CarryOver::Yes {
                carry_over_x_rigg(&existing, &mut normalized);
                carry_over_write_only(r.kind, &existing, &mut normalized);
            }
            // semantic_eq excludes write-only fields (the server never
            // echoes them) — compare them separately so a credentials
            // change alone still lands on disk.
            if crate::normalize::semantic_eq(r.kind, &existing, &normalized)
                && write_only_eq(r.kind, &existing, &normalized)
            {
                return Ok(false);
            }
        }

        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|source| StoreError::Io {
                path: parent.to_path_buf(),
                source,
            })?;
        }
        sidecar::extract_sidecars(r.kind, &path, &mut normalized)?;
        std::fs::write(&path, format_json(&normalized)).map_err(|source| StoreError::Io {
            path: path.clone(),
            source,
        })?;
        Ok(true)
    }

    /// Write a resource at an explicit STEM rather than its physical name —
    /// used by `rigg promote` when creating a resource in the target
    /// environment that has no counterpart there yet: the new file must land
    /// at the SOURCE environment's stem (its logical/correlation id) so the
    /// two trees keep correlating by path, even when the resource's physical
    /// `name` differs from that stem (a renamed resource in the source env).
    ///
    /// Unlike [`Store::write`] (which locates-or-creates by physical name),
    /// this never disambiguates: if `<stem>.json` already exists and holds a
    /// DIFFERENT physical name than `value`, that's a genuine collision (some
    /// other resource already occupies this stem) and it errors rather than
    /// overwriting or guessing a new path. When the existing file's physical
    /// name matches, it behaves like `write` (update in place, same
    /// x-rigg-*/write-only carry-over and semantic-no-op short circuit).
    pub fn write_at(&self, stem: &str, kind: ResourceKind, value: &Value) -> Result<bool> {
        self.write_at_inner(stem, kind, value, CarryOver::Yes)
    }

    /// [`Store::write_at`] with [`Store::write_exact`]'s rule: the document
    /// lands exactly as given, with no carry-over from the file it replaces.
    pub fn write_at_exact(&self, stem: &str, kind: ResourceKind, value: &Value) -> Result<bool> {
        self.write_at_inner(stem, kind, value, CarryOver::No)
    }

    fn write_at_inner(
        &self,
        stem: &str,
        kind: ResourceKind,
        value: &Value,
        carry: CarryOver,
    ) -> Result<bool> {
        validate_resource_name(stem).map_err(|e| StoreError::BadName {
            path: self.kind_dir(kind).join(format!("{stem}.json")),
            message: e.to_string(),
        })?;
        let path = self.kind_dir(kind).join(format!("{stem}.json"));
        let mut normalized = normalize_for_disk(kind, value);
        let new_name = normalized
            .get("name")
            .and_then(Value::as_str)
            .unwrap_or(stem)
            .to_string();

        if path.is_file() {
            let existing = self.read_path(&path)?;
            let existing_name = existing
                .get("name")
                .and_then(Value::as_str)
                .unwrap_or(stem)
                .to_string();
            if existing_name != new_name {
                return Err(StoreError::StemOccupiedByDifferentResource {
                    path,
                    existing_name,
                    new_name,
                });
            }
            if carry == CarryOver::Yes {
                carry_over_x_rigg(&existing, &mut normalized);
                carry_over_write_only(kind, &existing, &mut normalized);
            }
            if crate::normalize::semantic_eq(kind, &existing, &normalized)
                && write_only_eq(kind, &existing, &normalized)
            {
                return Ok(false);
            }
        }

        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|source| StoreError::Io {
                path: parent.to_path_buf(),
                source,
            })?;
        }
        sidecar::extract_sidecars(kind, &path, &mut normalized)?;
        std::fs::write(&path, format_json(&normalized)).map_err(|source| StoreError::Io {
            path: path.clone(),
            source,
        })?;
        Ok(true)
    }

    /// Delete a resource file (and its default sidecars). Only ever removes
    /// the file `locate` resolves for this physical name — deleting a name
    /// that matches nothing is a no-op (never falls through to a stem-guessed
    /// path that could belong to a renamed resource).
    pub fn delete(&self, r: &ResourceRef) -> Result<()> {
        let Some(path) = self.locate(r)? else {
            return Ok(());
        };
        // Sidecars are named after the file's stem (its logical id), which
        // may differ from the physical name — derive it from `path`, not `r`.
        let stem = path
            .file_stem()
            .map(|s| s.to_string_lossy().into_owned())
            .unwrap_or_else(|| r.name.clone());
        if path.is_file() {
            std::fs::remove_file(&path).map_err(|source| StoreError::Io {
                path: path.clone(),
                source,
            })?;
        }
        // Remove default sidecars (e.g. `<stem>.instructions.md`).
        if let Some(dir) = path.parent() {
            for field in crate::registry::meta(r.kind).sidecar_fields {
                let sidecar = dir.join(format!("{stem}.{field}.md"));
                if sidecar.is_file() {
                    let _ = std::fs::remove_file(sidecar);
                }
            }
        }
        Ok(())
    }
}

/// Raw (non-sidecar-inlining) read of a resource file's physical name: the
/// top-level `name` field if it's a string, else `fallback_stem`. Used by
/// `list`/`locate`, which only need the identity, not the full document.
fn physical_name(path: &Path, fallback_stem: &str) -> Result<String> {
    let text = std::fs::read_to_string(path).map_err(|source| StoreError::Io {
        path: path.to_path_buf(),
        source,
    })?;
    let value: Value = serde_json::from_str(&text).map_err(|source| StoreError::Parse {
        path: path.to_path_buf(),
        source,
    })?;
    Ok(value
        .get("name")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| fallback_stem.to_string()))
}

/// Whether two documents agree on every write-only field. `semantic_eq`
/// excludes these fields (the server never echoes them, so including them
/// would read every canonicalization as drift) — but a LOCAL write that
/// only changes a credential must still reach the disk.
fn write_only_eq(kind: ResourceKind, a: &Value, b: &Value) -> bool {
    crate::registry::meta(kind)
        .write_only_fields
        .iter()
        .all(|spec| write_only_values(a, spec) == write_only_values(b, spec))
}

/// The non-null values a document carries at one write-only field spec.
/// Nulls are dropped so that "absent" and "redacted to null" (Azure does
/// both, endpoint depending) compare equal — the same rule `canonical_form`
/// applies to the stored baseline.
fn write_only_values(doc: &Value, spec: &str) -> Vec<Value> {
    let mut out = Vec::new();
    crate::registry::collect_path(doc, spec, &mut |v| {
        if !v.is_null() {
            out.push(v.clone());
        }
    });
    out
}

/// Whether a write may take values from the file it replaces. Every write
/// that merges a REMOTE document into a local file carries over
/// ([`CarryOver::Yes`]); `rigg promote`, whose document is already the
/// finished local file, does not ([`CarryOver::No`]).
#[derive(Clone, Copy, PartialEq, Eq)]
enum CarryOver {
    Yes,
    No,
}

/// The document to record as a baseline after a sync wrote `doc` to disk.
///
/// `doc` is normally the server's echo, and Azure never echoes a write-only
/// field (a data source's `credentials.connectionString` comes back null or
/// absent). [`Store::write`] carries those values over from the local file,
/// so the baseline has to as well — otherwise it can never notice that the
/// user later re-pointed the data source at another storage account, and
/// `status`/`push` would call such an edit "in sync" forever.
pub fn baseline_doc(kind: ResourceKind, doc: &Value, local: Option<&Value>) -> Value {
    let mut out = doc.clone();
    if let Some(local) = local {
        carry_over_write_only(kind, local, &mut out);
    }
    out
}

/// Preserve write-only fields (server never echoes them) from the existing
/// local file when the incoming document lacks them or has them as null.
pub fn carry_over_write_only(kind: ResourceKind, from: &Value, to: &mut Value) {
    for spec in crate::registry::meta(kind).write_only_fields {
        let mut existing_value: Option<Value> = None;
        crate::registry::collect_path(from, spec, &mut |v| {
            if !v.is_null() {
                existing_value = Some(v.clone());
            }
        });
        let Some(existing_value) = existing_value else {
            continue;
        };
        set_path(to, &spec.split('.').collect::<Vec<_>>(), existing_value);
    }
}

/// Set a dot-path (no `[]` support — write-only fields are object paths),
/// creating intermediate objects as needed.
fn set_path(value: &mut Value, segments: &[&str], new_value: Value) {
    let Some((head, rest)) = segments.split_first() else {
        return;
    };
    let Value::Object(map) = value else { return };
    if rest.is_empty() {
        map.insert((*head).to_string(), new_value);
        return;
    }
    let entry = map
        .entry((*head).to_string())
        .or_insert_with(|| Value::Object(serde_json::Map::new()));
    set_path(entry, rest, new_value);
}

/// Copy `x-rigg-*` keys from `from` into `to` at the same paths (top-level and
/// one structural match deep for arrays keyed by `name`/`type`).
fn carry_over_x_rigg(from: &Value, to: &mut Value) {
    match (from, to) {
        (Value::Object(src), Value::Object(dst)) => {
            for (k, v) in src {
                if k.starts_with("x-rigg-") {
                    dst.entry(k.clone()).or_insert_with(|| v.clone());
                } else if let Some(dv) = dst.get_mut(k) {
                    carry_over_x_rigg(v, dv);
                }
            }
        }
        (Value::Array(src), Value::Array(dst)) => {
            for sv in src {
                let key = sv.get("name").or_else(|| sv.get("type"));
                if let Some(key) = key
                    && let Some(dv) = dst
                        .iter_mut()
                        .find(|d| d.get("name").or_else(|| d.get("type")) == Some(key))
                {
                    carry_over_x_rigg(sv, dv);
                }
            }
        }
        _ => {}
    }
}

/// Enforce exclusive ownership: a (kind, name) may appear in only one
/// project — within one environment (a physical resource named the same in
/// two envs is normal; it's the same logical resource pushed twice).
pub fn assert_exclusive_ownership(ws: &Workspace, env: &str) -> Result<()> {
    let mut seen: BTreeMap<ResourceRef, &str> = BTreeMap::new();
    for project in &ws.projects {
        let store = Store::new(project, env);
        for (r, _) in store.list()? {
            if let Some(first) = seen.get(&r) {
                return Err(StoreError::DuplicateOwnership {
                    reference: r.to_string(),
                    first: first.to_string(),
                    second: project.name.clone(),
                });
            }
            seen.insert(r, &project.name);
        }
    }
    Ok(())
}

/// Sync classification of one resource.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum SyncClass {
    /// Local, remote and baseline all agree.
    InSync,
    /// Local changed since last sync; remote unchanged.
    LocalAhead,
    /// Remote changed since last sync; local unchanged.
    RemoteAhead,
    /// Both changed since last sync.
    Conflict,
    /// Exists locally, not remotely (new resource or remote-deleted).
    LocalOnly,
    /// Exists remotely, not locally (unmanaged or locally-deleted).
    RemoteOnly,
    /// No baseline; local and remote both exist but differ (never synced).
    Untracked,
}

/// A sync baseline. Newer rigg versions store the push-normalized document
/// so the checksum can be recomputed under CURRENT normalization rules —
/// surviving rule evolution across rigg upgrades — and so the write-only
/// fields the checksum deliberately ignores are still on record. Legacy
/// entries hold only the frozen checksum and behave as before until the
/// resource next syncs (every successful pull/push/adopt rewrites its
/// baseline).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Baseline {
    /// Legacy: frozen checksum (string MUST be tried first — `Value`
    /// deserializes any JSON, including strings).
    Checksum(String),
    /// Push-normalized canonical document (write-only fields included).
    Doc(Value),
}

/// Per-project, per-environment sync baselines.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ProjectState {
    /// `kind-dir/name` → baseline captured at last sync.
    #[serde(default)]
    pub baselines: BTreeMap<String, Baseline>,
}

impl ProjectState {
    pub fn path(ws: &Workspace, env: &str, project: &str) -> PathBuf {
        ws.state_dir(env, project).join("state.json")
    }

    pub fn load(ws: &Workspace, env: &str, project: &str) -> ProjectState {
        let path = Self::path(ws, env, project);
        std::fs::read_to_string(&path)
            .ok()
            .and_then(|text| serde_json::from_str(&text).ok())
            .unwrap_or_default()
    }

    pub fn save(&self, ws: &Workspace, env: &str, project: &str) -> std::io::Result<()> {
        let path = Self::path(ws, env, project);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        std::fs::write(&path, format_json(&serde_json::to_value(self).unwrap()))
    }

    /// Checksum of the push-normalized form of a document.
    ///
    /// The form is canonicalized (object keys sorted recursively, arrays of
    /// named objects sorted by name) so that server-side reordering between
    /// GET and PUT responses never reads as a change — matching the semantics
    /// of the order-insensitive diff.
    pub fn checksum(kind: ResourceKind, value: &Value) -> String {
        let normalized = canonical_form(&normalize_for_compare(kind, value));
        let canonical = serde_json::to_string(&normalized).unwrap_or_default();
        format!("{:x}", md5_like(&canonical))
    }

    /// Whether a baseline is recorded for this resource.
    pub fn has_baseline(&self, r: &ResourceRef) -> bool {
        self.baselines.contains_key(&r.key())
    }

    /// Checksum of the recorded baseline, recomputed under CURRENT
    /// normalization rules for `Doc` entries — this is what lets a resource
    /// self-heal when a rigg upgrade changes which fields are volatile.
    /// Legacy `Checksum` entries are frozen and returned as-is.
    pub fn baseline_checksum(&self, r: &ResourceRef) -> Option<String> {
        match self.baselines.get(&r.key())? {
            Baseline::Checksum(s) => Some(s.clone()),
            Baseline::Doc(v) => Some(Self::checksum(r.kind, v)),
        }
    }

    /// The recorded baseline document, when one was stored (legacy
    /// checksum-only baselines have none).
    pub fn baseline_document(&self, r: &ResourceRef) -> Option<&Value> {
        match self.baselines.get(&r.key())? {
            Baseline::Checksum(_) => None,
            Baseline::Doc(v) => Some(v),
        }
    }

    /// Record a baseline. `kind_value` should be the document as it now
    /// exists on disk — see [`baseline_doc`], which merges the local file's
    /// write-only fields into a server echo that redacts them.
    pub fn set_baseline(&mut self, r: &ResourceRef, kind_value: &Value) {
        // `normalize_for_push`, not `normalize_for_compare`: the write-only
        // fields are kept so a later credentials-only local edit is visible.
        let doc = canonical_form(&normalize_for_push(r.kind, kind_value));
        self.baselines.insert(r.key(), Baseline::Doc(doc));
    }

    pub fn clear_baseline(&mut self, r: &ResourceRef) {
        self.baselines.remove(&r.key());
    }

    /// Whether the local document's write-only fields have moved away from
    /// the ones the baseline recorded.
    ///
    /// Answers `false` when the baseline is a legacy checksum-only entry: it
    /// records no values, so it cannot testify either way, and the old
    /// behaviour (write-only fields invisible to classification) stands until
    /// the resource next syncs.
    fn write_only_drifted(&self, r: &ResourceRef, local: &Value) -> bool {
        if crate::registry::meta(r.kind).write_only_fields.is_empty() {
            return false;
        }
        let Some(base) = self.baseline_document(r) else {
            return false;
        };
        !write_only_eq(r.kind, base, local)
    }

    /// Classify a resource given its (optional) local and remote documents.
    pub fn classify(
        &self,
        r: &ResourceRef,
        local: Option<&Value>,
        remote: Option<&Value>,
    ) -> SyncClass {
        let baseline = self.baseline_checksum(r);
        match (local, remote) {
            (None, None) => SyncClass::InSync, // nothing anywhere (only baseline leftover)
            (Some(_), None) => SyncClass::LocalOnly,
            (None, Some(_)) => SyncClass::RemoteOnly,
            (Some(l), Some(rm)) => {
                let lsum = Self::checksum(r.kind, l);
                let rsum = Self::checksum(r.kind, rm);
                match baseline {
                    None => {
                        if lsum == rsum {
                            SyncClass::InSync
                        } else {
                            SyncClass::Untracked
                        }
                    }
                    Some(base) => {
                        // Checksums ignore write-only fields (Azure redacts
                        // them, so including them would read as drift on
                        // every data source forever) — but a local edit that
                        // touches ONLY the credentials is still a change the
                        // user needs pushed. The baseline is the only side
                        // that can witness it; the remote never can.
                        let write_only_drift = self.write_only_drifted(r, l);
                        let local_changed = lsum != base || write_only_drift;
                        let remote_changed = rsum != base;
                        match (local_changed, remote_changed) {
                            (false, false) => SyncClass::InSync,
                            (true, false) => SyncClass::LocalAhead,
                            (false, true) => SyncClass::RemoteAhead,
                            (true, true) => {
                                if lsum != rsum {
                                    SyncClass::Conflict
                                } else if write_only_drift {
                                    // Same content both sides; only the local
                                    // credential moved.
                                    SyncClass::LocalAhead
                                } else {
                                    // Both moved to the same content.
                                    SyncClass::InSync
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

/// Order-canonical JSON: object keys sorted recursively; arrays whose items
/// all carry a string `name` are sorted by it (identity-keyed arrays).
fn canonical_form(value: &Value) -> Value {
    match value {
        Value::Object(map) => {
            // null-valued keys are dropped: Azure oscillates between omitting
            // a field and returning it as null depending on the endpoint.
            let mut sorted: Vec<(String, Value)> = map
                .iter()
                .filter(|(_, v)| !v.is_null())
                .map(|(k, v)| (k.clone(), canonical_form(v)))
                .collect();
            sorted.sort_by(|a, b| a.0.cmp(&b.0));
            Value::Object(sorted.into_iter().collect())
        }
        Value::Array(arr) => {
            let mut items: Vec<Value> = arr.iter().map(canonical_form).collect();
            if !items.is_empty()
                && items
                    .iter()
                    .all(|i| i.get("name").and_then(Value::as_str).is_some())
            {
                items.sort_by(|a, b| {
                    a["name"]
                        .as_str()
                        .unwrap_or_default()
                        .cmp(b["name"].as_str().unwrap_or_default())
                });
            }
            Value::Array(items)
        }
        other => other.clone(),
    }
}

/// Small non-cryptographic checksum (FNV-1a 128-ish via two 64-bit lanes).
/// Collision resistance is ample for change detection.
fn md5_like(s: &str) -> u128 {
    let mut h1: u64 = 0xcbf29ce484222325;
    let mut h2: u64 = 0x9e3779b97f4a7c15;
    for b in s.as_bytes() {
        h1 ^= u64::from(*b);
        h1 = h1.wrapping_mul(0x100000001b3);
        h2 = h2.rotate_left(5) ^ u64::from(*b);
        h2 = h2.wrapping_mul(0x2545f4914f6cdd1d);
    }
    (u128::from(h1) << 64) | u128::from(h2)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::workspace::{PROJECT_FILE, PROJECTS_DIR, WORKSPACE_FILE};
    use serde_json::json;

    fn ws_with_projects(dir: &Path, names: &[&str]) -> Workspace {
        std::fs::write(
            dir.join(WORKSPACE_FILE),
            "environments:\n  dev:\n    default: true\n    search: { service: s }\n",
        )
        .unwrap();
        for name in names {
            let pdir = dir.join(PROJECTS_DIR).join(name);
            std::fs::create_dir_all(&pdir).unwrap();
            std::fs::write(pdir.join(PROJECT_FILE), "{}\n").unwrap();
        }
        Workspace::load(dir).unwrap()
    }

    #[test]
    fn write_list_read_round_trip_with_sidecars() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");

        let agent_ref = ResourceRef::new(ResourceKind::Agent, "helper");
        let agent = json!({"name": "helper", "model": "gpt-5-mini", "instructions": "Be nice."});
        assert!(store.write(&agent_ref, &agent).unwrap());

        // sidecar extracted
        let sidecar = store
            .path_for(&agent_ref)
            .parent()
            .unwrap()
            .join("helper.instructions.md");
        assert!(sidecar.is_file());

        // read inlines it back
        let read = store.read(&agent_ref).unwrap();
        assert_eq!(read["instructions"], json!("Be nice."));

        let listed = store.list().unwrap();
        assert_eq!(listed.len(), 1);
        assert_eq!(listed[0].0, agent_ref);

        // env-rooted path
        assert!(
            store
                .path_for(&agent_ref)
                .to_string_lossy()
                .contains("envs/dev/")
        );
    }

    #[test]
    fn write_returns_false_when_semantically_unchanged() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::Index, "idx");
        assert!(
            store
                .write(&r, &json!({"name": "idx", "fields": []}))
                .unwrap()
        );
        // same content + volatile noise → no rewrite
        let noisy = json!({"@odata.etag": "0x1", "name": "idx", "fields": []});
        assert!(!store.write(&r, &noisy).unwrap());
        // real change → rewrite
        let changed = json!({"name": "idx", "fields": [{"name": "f"}]});
        assert!(store.write(&r, &changed).unwrap());
    }

    #[test]
    fn write_preserves_local_x_rigg_annotations() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::Skillset, "sk");
        let local = json!({
            "name": "sk",
            "skills": [{"name": "web", "uri": "https://f", "x-rigg-api": "enrich"}]
        });
        store.write(&r, &local).unwrap();
        // Azure returns the same thing without the annotation
        let remote = json!({
            "name": "sk",
            "skills": [{"name": "web", "uri": "https://f"}]
        });
        let rewritten = store.write(&r, &remote).unwrap();
        let read = store.read(&r).unwrap();
        assert_eq!(read["skills"][0]["x-rigg-api"], json!("enrich"));
        assert!(!rewritten, "annotation-only delta is not a semantic change");
    }

    #[test]
    fn write_exact_replaces_a_write_only_field_instead_of_carrying_it_over() {
        // `rigg promote` translates a data source's connection string into
        // the TARGET environment's storage account. `write` would copy the
        // old (source-pointing) string back over it — `write_exact` must
        // land the document exactly as given.
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        let r = ResourceRef::new(ResourceKind::DataSource, "ds");
        let ds = |account: &str| {
            json!({
                "name": "ds",
                "type": "azureblob",
                "credentials": {"connectionString": format!("ResourceId=/{account};")},
                "container": {"name": "c"},
            })
        };
        assert!(store.write(&r, &ds("devacct")).unwrap());
        assert!(
            store.write_exact(&r, &ds("prodacct")).unwrap(),
            "the rewired connection string is a change"
        );
        let read = store.read(&r).unwrap();
        assert_eq!(
            read["credentials"]["connectionString"],
            json!("ResourceId=/prodacct;"),
            "write_exact must not resurrect the previous write-only value"
        );
        assert!(
            !store.write_exact(&r, &ds("prodacct")).unwrap(),
            "write_exact is still a no-op when nothing changed"
        );
    }

    #[test]
    fn write_exact_does_not_carry_over_x_rigg_annotations() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::Skillset, "sk");
        store
            .write(
                &r,
                &json!({"name": "sk", "description": "old", "x-rigg-pin": ["a"], "skills": []}),
            )
            .unwrap();
        assert!(
            store
                .write_exact(
                    &r,
                    &json!({"name": "sk", "description": "new", "skills": []})
                )
                .unwrap()
        );
        let read = store.read(&r).unwrap();
        assert!(
            read.get("x-rigg-pin").is_none(),
            "write_exact writes the document as given: {read}"
        );
    }

    #[test]
    fn write_at_exact_replaces_a_write_only_field_instead_of_carrying_it_over() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        let ds = |account: &str| {
            json!({
                "name": "ds",
                "type": "azureblob",
                "credentials": {"connectionString": format!("ResourceId=/{account};")},
                "container": {"name": "c"},
            })
        };
        store
            .write_at("docs", ResourceKind::DataSource, &ds("devacct"))
            .unwrap();
        assert!(
            store
                .write_at_exact("docs", ResourceKind::DataSource, &ds("prodacct"))
                .unwrap()
        );
        let dir = store.kind_dir(ResourceKind::DataSource);
        let on_disk: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("docs.json")).unwrap()).unwrap();
        assert_eq!(
            on_disk["credentials"]["connectionString"],
            json!("ResourceId=/prodacct;")
        );
    }

    #[test]
    fn exclusive_ownership_violation_names_both_projects() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["alpha", "beta"]);
        for p in ["alpha", "beta"] {
            let store = Store::new(ws.project(p).unwrap(), "dev");
            store
                .write(
                    &ResourceRef::new(ResourceKind::Index, "shared"),
                    &json!({"name": "shared"}),
                )
                .unwrap();
        }
        let err = assert_exclusive_ownership(&ws, "dev").unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("alpha") && msg.contains("beta") && msg.contains("indexes/shared"));
    }

    #[test]
    fn ownership_is_scoped_per_environment() {
        // Same physical name in two projects but DIFFERENT envs: not a
        // violation (ownership is checked per env tree).
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["alpha", "beta"]);
        Store::new(ws.project("alpha").unwrap(), "dev")
            .write(
                &ResourceRef::new(ResourceKind::Index, "shared"),
                &json!({"name": "shared"}),
            )
            .unwrap();
        Store::new(ws.project("beta").unwrap(), "prod")
            .write(
                &ResourceRef::new(ResourceKind::Index, "shared"),
                &json!({"name": "shared"}),
            )
            .unwrap();
        assert!(assert_exclusive_ownership(&ws, "dev").is_ok());
        assert!(assert_exclusive_ownership(&ws, "prod").is_ok());
    }

    #[test]
    fn envs_of_lists_env_dirs_sorted() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let project = ws.project("p").unwrap();
        assert_eq!(Store::envs_of(project), Vec::<String>::new());
        Store::new(project, "prod")
            .write(
                &ResourceRef::new(ResourceKind::Index, "idx"),
                &json!({"name": "idx"}),
            )
            .unwrap();
        Store::new(project, "dev")
            .write(
                &ResourceRef::new(ResourceKind::Index, "idx"),
                &json!({"name": "idx"}),
            )
            .unwrap();
        assert_eq!(Store::envs_of(project), vec!["dev", "prod"]);
    }

    #[test]
    fn list_keys_by_physical_name_when_stem_differs() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("regulus.json"),
            json!({"name": "Regulus-Prod", "model": "m"}).to_string(),
        )
        .unwrap();
        let listed = store.list().unwrap();
        assert_eq!(listed.len(), 1);
        assert_eq!(listed[0].0.name, "Regulus-Prod");
        assert_eq!(listed[0].1, dir.join("regulus.json"));
    }

    #[test]
    fn locate_finds_file_by_physical_name_when_stem_differs() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("regulus.json"),
            json!({"name": "Regulus-Prod", "model": "m"}).to_string(),
        )
        .unwrap();
        let found = store
            .locate(&ResourceRef::new(ResourceKind::Agent, "Regulus-Prod"))
            .unwrap();
        assert_eq!(found, Some(dir.join("regulus.json")));
        assert_eq!(
            store
                .locate(&ResourceRef::new(ResourceKind::Agent, "regulus"))
                .unwrap(),
            None,
            "the stem alone is not a physical name once name diverges"
        );
    }

    #[test]
    fn write_updates_the_located_file_not_a_stem_guess() {
        // Physical rename case: file `regulus.json` holds name "Regulus-Prod".
        // Writing a ResourceRef keyed on the physical name must update THAT
        // file in place, not create a new `Regulus-Prod.json`.
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("regulus.json"),
            json!({"name": "Regulus-Prod", "model": "m1"}).to_string(),
        )
        .unwrap();
        let r = ResourceRef::new(ResourceKind::Agent, "Regulus-Prod");
        store
            .write(&r, &json!({"name": "Regulus-Prod", "model": "m2"}))
            .unwrap();
        assert!(
            !dir.join("Regulus-Prod.json").exists(),
            "must not create a second file keyed on the physical name"
        );
        let on_disk: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("regulus.json")).unwrap())
                .unwrap();
        assert_eq!(on_disk["model"], json!("m2"));
    }

    #[test]
    fn write_never_overwrites_a_renamed_resources_stem() {
        // `regulus.json` holds physical name "Regulus-Prod" (a renamed
        // resource). Creating a NEW resource whose physical name is
        // "regulus" must NOT clobber it: the create path disambiguates to a
        // free stem instead.
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("regulus.json"),
            json!({"name": "Regulus-Prod", "model": "m"}).to_string(),
        )
        .unwrap();

        let r = ResourceRef::new(ResourceKind::Agent, "regulus");
        assert!(
            store
                .write(&r, &json!({"name": "regulus", "model": "new"}))
                .unwrap()
        );

        // the renamed resource's file is untouched
        let original: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("regulus.json")).unwrap())
                .unwrap();
        assert_eq!(
            original["name"],
            json!("Regulus-Prod"),
            "original file untouched"
        );

        // the new resource landed at a different, disambiguated stem
        let new_path = store.locate(&r).unwrap().expect("new resource locatable");
        assert_ne!(new_path, dir.join("regulus.json"));
        assert_eq!(new_path, dir.join("regulus-2.json"));

        // both resolve correctly by physical name
        assert_eq!(
            store
                .locate(&ResourceRef::new(ResourceKind::Agent, "Regulus-Prod"))
                .unwrap(),
            Some(dir.join("regulus.json"))
        );
        assert_eq!(store.list().unwrap().len(), 2);
    }

    #[test]
    fn delete_by_physical_name_removes_located_file_and_stem_sidecars() {
        // File stem "regulus" ≠ physical name "Regulus-Prod", with an
        // instructions sidecar named after the STEM. Deleting by physical
        // name must remove the located file AND its stem-named sidecar,
        // leaving a neighboring resource untouched.
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("regulus.json"),
            json!({
                "name": "Regulus-Prod", "model": "m",
                "instructions": {"$file": "regulus.instructions.md"}
            })
            .to_string(),
        )
        .unwrap();
        std::fs::write(dir.join("regulus.instructions.md"), "Be helpful.").unwrap();
        // neighbor with its own sidecar
        std::fs::write(
            dir.join("other.json"),
            json!({
                "name": "other", "model": "m",
                "instructions": {"$file": "other.instructions.md"}
            })
            .to_string(),
        )
        .unwrap();
        std::fs::write(dir.join("other.instructions.md"), "Neighbor.").unwrap();

        store
            .delete(&ResourceRef::new(ResourceKind::Agent, "Regulus-Prod"))
            .unwrap();
        assert!(!dir.join("regulus.json").exists(), "located file removed");
        assert!(
            !dir.join("regulus.instructions.md").exists(),
            "stem-named sidecar removed"
        );
        assert!(dir.join("other.json").exists(), "neighbor untouched");
        assert!(
            dir.join("other.instructions.md").exists(),
            "neighbor sidecar untouched"
        );

        // deleting a physical name that matches nothing is a no-op
        store
            .delete(&ResourceRef::new(ResourceKind::Agent, "ghost"))
            .unwrap();
        assert!(dir.join("other.json").exists());
    }

    #[test]
    fn list_error_on_corrupt_json_names_the_file() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Index, "a"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("broken.json"), "{ this is not json").unwrap();
        let err = store.list().unwrap_err();
        assert!(matches!(err, StoreError::Parse { .. }));
        assert!(
            err.to_string().contains("broken.json"),
            "error names the broken file: {err}"
        );
    }

    #[test]
    fn duplicate_physical_name_in_one_kind_dir_errors() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Index, "a"))
            .parent()
            .unwrap()
            .to_path_buf();
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("a.json"), json!({"name": "dup"}).to_string()).unwrap();
        std::fs::write(dir.join("b.json"), json!({"name": "dup"}).to_string()).unwrap();
        let err = store.list().unwrap_err();
        assert!(matches!(err, StoreError::DuplicatePhysicalName { .. }));
        assert!(err.to_string().contains("dup"));
    }

    #[test]
    fn classify_truth_table() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let r = ResourceRef::new(ResourceKind::Index, "idx");
        let a = json!({"name": "idx", "fields": [{"name": "f1"}]});
        let b = json!({"name": "idx", "fields": [{"name": "f2"}]});
        let c = json!({"name": "idx", "fields": [{"name": "f3"}]});

        let mut state = ProjectState::default();
        // no baseline
        assert_eq!(state.classify(&r, Some(&a), Some(&a)), SyncClass::InSync);
        assert_eq!(state.classify(&r, Some(&a), Some(&b)), SyncClass::Untracked);
        assert_eq!(state.classify(&r, Some(&a), None), SyncClass::LocalOnly);
        assert_eq!(state.classify(&r, None, Some(&a)), SyncClass::RemoteOnly);
        assert_eq!(state.classify(&r, None, None), SyncClass::InSync);

        // with baseline = a
        state.set_baseline(&r, &a);
        assert_eq!(state.classify(&r, Some(&a), Some(&a)), SyncClass::InSync);
        assert_eq!(
            state.classify(&r, Some(&b), Some(&a)),
            SyncClass::LocalAhead
        );
        assert_eq!(
            state.classify(&r, Some(&a), Some(&b)),
            SyncClass::RemoteAhead
        );
        assert_eq!(state.classify(&r, Some(&b), Some(&c)), SyncClass::Conflict);
        assert_eq!(state.classify(&r, Some(&b), Some(&b)), SyncClass::InSync);

        // save/load round trip
        state.save(&ws, "dev", "p").unwrap();
        let loaded = ProjectState::load(&ws, "dev", "p");
        assert_eq!(loaded.baseline_checksum(&r), state.baseline_checksum(&r));
    }

    #[test]
    fn legacy_checksum_baseline_still_loads_and_classifies() {
        // A state.json written by an older rigg: baseline is a bare string.
        let json = r#"{"baselines": {"agents/a": "deadbeef"}}"#;
        let state: ProjectState = serde_json::from_str(json).unwrap();
        let r = ResourceRef::new(ResourceKind::Agent, "a".to_string());
        assert!(state.has_baseline(&r));
        // Stale hash + differing local/remote → Conflict (today's behavior).
        let local = json!({"name": "a", "model": "x"});
        let remote = json!({"name": "a", "model": "y"});
        assert_eq!(
            state.classify(&r, Some(&local), Some(&remote)),
            SyncClass::Conflict
        );
    }

    #[test]
    fn doc_baseline_self_heals_across_rule_changes() {
        // Simulate a baseline stored BEFORE metadata.modified_at became
        // volatile: the stored doc still carries the field. Under current
        // rules the recomputed checksum strips it, so an untouched local
        // (without the field) plus a remote-only change classifies as
        // RemoteAhead — NOT Conflict.
        let r = ResourceRef::new(ResourceKind::Agent, "a".to_string());
        let old_doc = json!({
            "name": "a", "model": "x",
            "metadata": {"modified_at": "111", "logo": "l.svg"}
        });
        let mut state = ProjectState::default();
        state.baselines.insert(r.key(), Baseline::Doc(old_doc));
        let local = json!({
            "name": "a", "model": "x", "metadata": {"logo": "l.svg"}
        });
        let remote = json!({
            "name": "a", "model": "CHANGED", "metadata": {"logo": "l.svg"}
        });
        assert_eq!(
            state.classify(&r, Some(&local), Some(&remote)),
            SyncClass::RemoteAhead
        );
    }

    #[test]
    fn baseline_serde_mixed_roundtrip() {
        let r = ResourceRef::new(ResourceKind::Agent, "new".to_string());
        let mut state = ProjectState::default();
        state.baselines.insert(
            "agents/legacy".to_string(),
            Baseline::Checksum("abc".to_string()),
        );
        state.set_baseline(&r, &json!({"name": "new", "model": "m"}));
        let text = serde_json::to_string(&state).unwrap();
        let back: ProjectState = serde_json::from_str(&text).unwrap();
        assert!(
            matches!(back.baselines.get("agents/legacy"), Some(Baseline::Checksum(s)) if s == "abc")
        );
        assert!(matches!(
            back.baselines.get("agents/new"),
            Some(Baseline::Doc(_))
        ));
    }

    #[test]
    fn a_credential_only_local_edit_classifies_as_local_ahead() {
        // Regression: checksums ignore write-only fields, so re-pointing a
        // data source at another storage account used to classify as InSync
        // and `push` skipped it — the credential could never be rotated.
        let r = ResourceRef::new(ResourceKind::DataSource, "ds");
        let ds = |conn: &str| {
            json!({
                "name": "ds", "type": "azureblob",
                "credentials": {"connectionString": conn},
                "container": {"name": "c"}
            })
        };
        let local_a = ds("ResourceId=/subscriptions/s/…/storageAccounts/acct-a;");
        let local_b = ds("ResourceId=/subscriptions/s/…/storageAccounts/acct-b;");
        // Azure's GET redacts the connection string to null, always.
        let remote = json!({
            "name": "ds", "type": "azureblob",
            "credentials": {"connectionString": null},
            "container": {"name": "c"}
        });

        let mut state = ProjectState::default();
        state.set_baseline(&r, &local_a);
        assert_eq!(
            state.classify(&r, Some(&local_a), Some(&remote)),
            SyncClass::InSync,
            "unchanged credentials against a redacted remote stay in sync"
        );
        assert_eq!(
            state.classify(&r, Some(&local_b), Some(&remote)),
            SyncClass::LocalAhead,
            "a new connection string is a pending local change"
        );

        // A legacy checksum-only baseline records no values and cannot
        // testify: the old behaviour stands until the resource next syncs.
        state.baselines.insert(
            r.key(),
            Baseline::Checksum(ProjectState::checksum(r.kind, &local_a)),
        );
        assert_eq!(
            state.classify(&r, Some(&local_b), Some(&remote)),
            SyncClass::InSync
        );
    }

    #[test]
    fn credential_only_change_still_writes() {
        // Regression: semantic_eq excludes write-only fields, so a write
        // whose ONLY change is a new credentials.connectionString used to be
        // skipped as "no change" — the migrate/push credential fixups then
        // never landed on disk.
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::DataSource, "ds");
        let without = json!({
            "name": "ds", "type": "azureblob",
            "credentials": {"connectionString": null},
            "container": {"name": "c"}
        });
        store.write(&r, &without).unwrap();
        let mut with = without.clone();
        with["credentials"]["connectionString"] = json!("ResourceId=/subscriptions/s/x;");
        assert!(
            store.write(&r, &with).unwrap(),
            "credential change must write"
        );
        let read = store.read(&r).unwrap();
        assert_eq!(
            read["credentials"]["connectionString"],
            json!("ResourceId=/subscriptions/s/x;")
        );
    }

    #[test]
    fn write_only_fields_survive_server_echo_and_compare() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::DataSource, "ds");
        let local = json!({
            "name": "ds", "type": "azureblob",
            "credentials": {"connectionString": "ResourceId=/subscriptions/s/x;"},
            "container": {"name": "c"}
        });
        store.write(&r, &local).unwrap();
        // Azure's GET echo: connection string redacted to null
        let server_echo = json!({
            "name": "ds", "type": "azureblob",
            "credentials": {"connectionString": null},
            "container": {"name": "c"}
        });
        // no semantic change → no rewrite, and the conn string survives
        assert!(!store.write(&r, &server_echo).unwrap());
        let read = store.read(&r).unwrap();
        assert_eq!(
            read["credentials"]["connectionString"],
            json!("ResourceId=/subscriptions/s/x;")
        );
        // checksums ignore the write-only field (local vs redacted remote equal)
        assert_eq!(
            ProjectState::checksum(ResourceKind::DataSource, &local),
            ProjectState::checksum(ResourceKind::DataSource, &server_echo)
        );
    }

    #[test]
    fn checksum_is_order_canonical() {
        // same content, different key order and array order
        let a = serde_json::from_str::<Value>(
            r#"{"name": "i", "fields": [{"name": "b"}, {"name": "a"}], "x": 1}"#,
        )
        .unwrap();
        let b = serde_json::from_str::<Value>(
            r#"{"x": 1, "name": "i", "fields": [{"name": "a"}, {"name": "b"}]}"#,
        )
        .unwrap();
        assert_eq!(
            ProjectState::checksum(ResourceKind::Index, &a),
            ProjectState::checksum(ResourceKind::Index, &b)
        );
    }

    #[test]
    fn checksum_ignores_volatile_and_annotations() {
        let a = json!({"name": "i", "@odata.etag": "1", "x-rigg-note": "hi"});
        let b = json!({"name": "i"});
        assert_eq!(
            ProjectState::checksum(ResourceKind::Index, &a),
            ProjectState::checksum(ResourceKind::Index, &b)
        );
    }

    #[test]
    fn write_at_creates_file_at_given_stem() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        let created = store
            .write_at(
                "regulus",
                ResourceKind::Agent,
                &json!({"name": "Regulus-Prod", "model": "m"}),
            )
            .unwrap();
        assert!(created);
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        assert!(
            dir.join("regulus.json").is_file(),
            "landed at the stem, not the physical name"
        );
        assert!(!dir.join("Regulus-Prod.json").exists());
        let on_disk: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("regulus.json")).unwrap())
                .unwrap();
        assert_eq!(on_disk["name"], json!("Regulus-Prod"));
    }

    #[test]
    fn write_at_updates_in_place_when_physical_name_matches() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        store
            .write_at(
                "regulus",
                ResourceKind::Agent,
                &json!({"name": "Regulus-Prod", "model": "m1"}),
            )
            .unwrap();
        let rewritten = store
            .write_at(
                "regulus",
                ResourceKind::Agent,
                &json!({"name": "Regulus-Prod", "model": "m2"}),
            )
            .unwrap();
        assert!(rewritten);
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        let on_disk: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("regulus.json")).unwrap())
                .unwrap();
        assert_eq!(on_disk["model"], json!("m2"));
    }

    #[test]
    fn write_at_refuses_to_overwrite_a_different_resources_stem() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        store
            .write_at(
                "regulus",
                ResourceKind::Agent,
                &json!({"name": "Regulus-Prod", "model": "m1"}),
            )
            .unwrap();
        let err = store
            .write_at(
                "regulus",
                ResourceKind::Agent,
                &json!({"name": "some-other-name", "model": "m2"}),
            )
            .unwrap_err();
        assert!(matches!(
            err,
            StoreError::StemOccupiedByDifferentResource { .. }
        ));
        // original untouched
        let dir = store
            .path_for(&ResourceRef::new(ResourceKind::Agent, "regulus"))
            .parent()
            .unwrap()
            .to_path_buf();
        let on_disk: Value =
            serde_json::from_str(&std::fs::read_to_string(dir.join("regulus.json")).unwrap())
                .unwrap();
        assert_eq!(on_disk["name"], json!("Regulus-Prod"));
    }

    #[test]
    fn write_at_returns_false_when_semantically_unchanged() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        store
            .write_at(
                "idx",
                ResourceKind::Index,
                &json!({"name": "idx", "fields": []}),
            )
            .unwrap();
        let rewritten = store
            .write_at(
                "idx",
                ResourceKind::Index,
                &json!({"@odata.etag": "0x1", "name": "idx", "fields": []}),
            )
            .unwrap();
        assert!(!rewritten);
    }

    #[test]
    fn write_at_rejects_path_escaping_stems() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "prod");
        let err = store.write_at("../../evil", ResourceKind::Index, &json!({"name": "evil"}));
        assert!(matches!(err, Err(StoreError::BadName { .. })), "{err:?}");
    }

    #[test]
    fn write_rejects_path_escaping_names() {
        let tmp = tempfile::tempdir().unwrap();
        let ws = ws_with_projects(tmp.path(), &["p"]);
        let store = Store::new(ws.project("p").unwrap(), "dev");
        let r = ResourceRef::new(ResourceKind::Index, "../../evil");
        let err = store.write(&r, &json!({"name": "../../evil"}));
        assert!(matches!(err, Err(StoreError::BadName { .. })), "{err:?}");
    }
}