automorph 0.2.0

//! Core traits for Automerge synchronization.
//!
//! This module defines the primary `Automorph` trait that types must implement to
//! synchronize with Automerge documents, along with supporting traits for efficient
//! change tracking.

use std::borrow::Cow;
use std::collections::HashSet;
use std::fmt::Debug;
use std::hash::Hash;
use std::ops::Deref;

use automerge::{ChangeHash, ObjId, Prop, ReadDoc, transaction::Transactable};

use crate::Result;

// =============================================================================
// Core Trait: Automorph
// =============================================================================

/// Primary trait for bidirectional synchronization with Automerge documents.
///
/// This trait enables Rust types to synchronize their state with Automerge
/// documents. It provides:
///
/// - **Core operations**: Write to (`save`) and read from (`load`) Automerge documents
/// - **In-place updates**: Update existing instances via `update`
/// - **Change tracking**: Know which fields changed via `diff`
/// - **Version-aware operations**: Work with historical document states via `*_at` methods
/// - **Efficient tracking**: O(1) change detection via `Tracked<T>` wrapper
///
/// # Derive Macro
///
/// The easiest way to implement this trait is using the derive macro:
///
/// ```rust
/// use automorph::Automorph;
/// use automerge::{AutoCommit, ROOT};
///
/// #[derive(Automorph, Default, Clone, Debug, PartialEq)]
/// struct Person {
///     name: String,
///     age: u64,
/// }
///
/// let mut doc = AutoCommit::new();
/// let person = Person { name: "Alice".to_string(), age: 30 };
/// person.save(&mut doc, &ROOT, "person").unwrap();
///
/// let loaded = Person::load(&doc, &ROOT, "person").unwrap();
/// assert_eq!(person, loaded);
/// ```
///
/// # Associated Types
///
/// - `Changes`: Hierarchical change report for deep inspection
/// - `Cursor`: Cached ObjIds for O(1) change detection
///
/// # Example
///
/// ```rust
/// use automorph::Automorph;
/// use automerge::{AutoCommit, ROOT};
///
/// fn example() -> Result<(), Box<dyn std::error::Error>> {
///     let mut doc = AutoCommit::new();
///
///     // Write to document
///     let value = "hello".to_string();
///     value.save(&mut doc, &ROOT, "greeting")?;
///
///     // Read from document
///     let restored = String::load(&doc, &ROOT, "greeting")?;
///     assert_eq!(restored, "hello");
///
///     // Read from specific version
///     let heads = doc.get_heads();
///     let at_version = String::load_at(&doc, &ROOT, "greeting", &heads)?;
///     Ok(())
/// }
/// ```
pub trait Automorph: Sized {
    /// Hierarchical change report type for deep change inspection.
    ///
    /// For primitive types, this is `PrimitiveChanged`.
    /// For structs, this is a generated `*Changes` struct that mirrors the
    /// field hierarchy, enabling inspection like:
    /// `changes.name` (bool for primitives) or `changes.address` (`Option<AddressChanges>`).
    type Changes: ChangeReport;

    /// Cursor type for O(1) change detection via cached ObjIds.
    ///
    /// Used internally by `Tracked<T>` to enable efficient change detection
    /// without deserializing the entire document.
    type Cursor: FieldCursor;

    // =========================================================================
    // Required Methods (3)
    // =========================================================================

    /// Synchronizes this value to an Automerge document.
    ///
    /// This method writes the current state of `self` to the specified location
    /// in the Automerge document. It uses efficient diffing to only write values
    /// that have actually changed.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to write to
    /// * `obj` - The parent object ID (use `ROOT` for the document root)
    /// * `prop` - The property name or index to write to
    ///
    /// # Errors
    ///
    /// Returns an error if the Automerge document operation fails.
    fn save<D: Transactable + ReadDoc>(
        &self,
        doc: &mut D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
    ) -> Result<()>;

    /// Creates a new instance from a specific version of an Automerge document.
    ///
    /// This is the core loading method. All other loading methods delegate to this.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID (use `ROOT` for the document root)
    /// * `prop` - The property name or index to read from
    /// * `heads` - The change hashes representing the document version
    ///
    /// # Errors
    ///
    /// Returns an error if the value doesn't exist or has an incompatible type.
    fn load_at<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        heads: &[ChangeHash],
    ) -> Result<Self>;

    /// Compares this value against a specific document version.
    ///
    /// Returns a `ChangeReport` describing which fields differ.
    ///
    /// # Implementation Notes
    ///
    /// For optimal performance, implementations should compare field-by-field
    /// without allocating a new struct. However, for types where this isn't
    /// practical (like enums where the variant must be determined first),
    /// calling `load_at()` and comparing is acceptable.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to compare against
    /// * `obj` - The parent object ID
    /// * `prop` - The property name or index
    /// * `heads` - The change hashes representing the document version
    fn diff_at<D: ReadDoc>(
        &self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        heads: &[ChangeHash],
    ) -> Result<Self::Changes>;

    // =========================================================================
    // Convenience Methods (with default implementations)
    // =========================================================================

    /// Creates a new instance from the current document state.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID (use `ROOT` for the document root)
    /// * `prop` - The property name or index to read from
    ///
    /// # Errors
    ///
    /// Returns an error if the value doesn't exist or has an incompatible type.
    ///
    /// # Note
    ///
    /// This method uses `doc.get()` to read current state.
    /// For reading historical versions, use `load_at()` instead.
    fn load<D: ReadDoc>(doc: &D, obj: impl AsRef<ObjId>, prop: impl Into<Prop>) -> Result<Self>;

    /// Updates this value in place from the current document state.
    ///
    /// Returns a `ChangeReport` describing which fields were modified.
    ///
    /// # Implementation Notes
    ///
    /// For optimal performance, implementations should walk each field individually
    /// and only update fields that changed. However, for types where this isn't
    /// practical (like enums or primitives), calling `load()` and replacing
    /// the value is acceptable.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID
    /// * `prop` - The property name or index
    ///
    /// # Errors
    ///
    /// Returns an error if the value doesn't exist or has an incompatible type.
    fn update<D: ReadDoc>(
        &mut self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
    ) -> Result<Self::Changes>;

    /// Updates this value in place from a specific document version.
    ///
    /// Returns a `ChangeReport` describing which fields were modified.
    ///
    /// # Implementation Notes
    ///
    /// For optimal performance, implementations should walk each field individually
    /// and only update fields that changed. However, for types where this isn't
    /// practical (like enums or primitives), calling `load_at()` and replacing
    /// the value is acceptable.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID
    /// * `prop` - The property name or index
    /// * `heads` - The change hashes representing the document version
    ///
    /// # Errors
    ///
    /// Returns an error if the value doesn't exist or has an incompatible type.
    fn update_at<D: ReadDoc>(
        &mut self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        heads: &[ChangeHash],
    ) -> Result<Self::Changes>;

    /// Compares this value against the current document state.
    ///
    /// Returns a `ChangeReport` describing which fields differ.
    ///
    /// # Implementation Notes
    ///
    /// For optimal performance, implementations should compare field-by-field
    /// without allocating a new struct. However, for types where this isn't
    /// practical (like enums where the variant must be determined first),
    /// calling `load()` and comparing is acceptable.
    fn diff<D: ReadDoc>(
        &self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
    ) -> Result<Self::Changes>;

    /// Compares two document versions to find which fields changed.
    ///
    /// This is a static method that doesn't require an existing Rust value.
    /// Useful for understanding what changed between two points in time.
    fn diff_versions<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        from_heads: &[ChangeHash],
        to_heads: &[ChangeHash],
    ) -> Result<Self::Changes> {
        let obj = obj.as_ref();
        let prop: Prop = prop.into();
        let from_value = Self::load_at(doc, obj, prop.clone(), from_heads)?;
        from_value.diff_at(doc, obj, prop, to_heads)
    }

    /// Loads a value from the document wrapped in a `Tracked<T>` for O(1) change detection.
    ///
    /// `Tracked<T>` caches the ObjIds for each field, enabling efficient change detection
    /// without deserializing and comparing values.
    fn tracked<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
    ) -> Result<Tracked<Self>> {
        Tracked::load(doc, obj, prop)
    }

    /// Loads a value from a specific document version wrapped in `Tracked<T>`.
    fn tracked_at<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        heads: &[ChangeHash],
    ) -> Result<Tracked<Self>> {
        Tracked::load_at(doc, obj, prop, heads)
    }

    // =========================================================================
    // Flatten Methods (for #[automorph(flatten)])
    // =========================================================================

    /// Saves this struct's fields directly to the parent object.
    ///
    /// Used by `#[automorph(flatten)]` to inline a struct's fields into the parent
    /// object instead of creating a nested object.
    ///
    /// For primitive types, this delegates to `save`. For struct types,
    /// the derive macro generates an implementation that saves each field
    /// directly to the parent object.
    fn save_flat<D: Transactable + ReadDoc>(
        &self,
        doc: &mut D,
        obj: impl AsRef<ObjId>,
    ) -> Result<()>
    where
        Self: Automorph,
    {
        // Default implementation delegates to save with empty key
        // This works for primitive types but structs should override
        self.save(doc, obj, "")
    }

    /// Loads this struct's fields directly from the parent object.
    ///
    /// Used by `#[automorph(flatten)]` to load a struct's fields from the parent
    /// object level instead of from a nested object.
    fn load_flat<D: ReadDoc>(doc: &D, obj: impl AsRef<ObjId>) -> Result<Self>
    where
        Self: Automorph,
    {
        // Default implementation delegates to load with empty key
        Self::load(doc, obj, "")
    }

    /// Loads this struct's fields directly from the parent object at a specific version.
    fn load_flat_at<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        heads: &[ChangeHash],
    ) -> Result<Self>
    where
        Self: Automorph,
    {
        // Default implementation delegates to load_at with empty key
        Self::load_at(doc, obj, "", heads)
    }

    /// Computes diff for flattened fields.
    ///
    /// Used by `#[automorph(flatten)]` to compare against fields at the parent
    /// object level instead of a nested object.
    fn diff_flat<D: ReadDoc>(
        &self,
        doc: &D,
        obj: impl AsRef<ObjId>,
    ) -> Result<Self::Changes>
    where
        Self: Automorph,
    {
        // Default implementation delegates to diff with empty key
        self.diff(doc, obj, "")
    }

    /// Computes diff for flattened fields at a specific version.
    fn diff_flat_at<D: ReadDoc>(
        &self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        heads: &[ChangeHash],
    ) -> Result<Self::Changes>
    where
        Self: Automorph,
    {
        // Default implementation delegates to diff_at with empty key
        self.diff_at(doc, obj, "", heads)
    }

    /// Updates this struct's fields directly from the parent object.
    ///
    /// Used by `#[automorph(flatten)]` to update fields from the parent
    /// object level instead of a nested object.
    fn update_flat<D: ReadDoc>(
        &mut self,
        doc: &D,
        obj: impl AsRef<ObjId>,
    ) -> Result<Self::Changes>
    where
        Self: Automorph,
    {
        // Default implementation delegates to update with empty key
        self.update(doc, obj, "")
    }

    /// Updates this struct's fields directly from the parent object at a specific version.
    fn update_flat_at<D: ReadDoc>(
        &mut self,
        doc: &D,
        obj: impl AsRef<ObjId>,
        heads: &[ChangeHash],
    ) -> Result<Self::Changes>
    where
        Self: Automorph,
    {
        // Default implementation delegates to update_at with empty key
        self.update_at(doc, obj, "", heads)
    }
}

// =============================================================================
// Change Report Trait
// =============================================================================

/// Trait for hierarchical change reports.
///
/// Generated `*Changes` types implement this trait to provide a uniform interface
/// for inspecting what changed in a document update.
///
/// # Example
///
/// ```rust
/// use automorph::{Automorph, ChangeReport};
/// use automerge::{AutoCommit, ROOT};
///
/// #[derive(Automorph, Debug, PartialEq, Default, Clone)]
/// struct Person {
///     name: String,
///     age: u32,
/// }
///
/// fn handle_changes(changes: &<Person as Automorph>::Changes) {
///     if changes.any() {
///         for path in changes.leaf_paths() {
///             println!("Changed: {:?}", path);
///         }
///     }
/// }
///
/// let mut doc = AutoCommit::new();
/// let person = Person { name: "Alice".to_string(), age: 30 };
/// person.save(&mut doc, &ROOT, "person").unwrap();
///
/// let person2 = Person { name: "Bob".to_string(), age: 30 };
/// let changes = person2.diff(&doc, &ROOT, "person").unwrap();
/// handle_changes(&changes);
/// ```
pub trait ChangeReport: Default + Clone + Debug {
    /// Returns true if any field in this report (or nested reports) changed.
    fn any(&self) -> bool;

    /// Returns true if no fields changed.
    fn none(&self) -> bool {
        !self.any()
    }

    /// Collects all changed field paths as strings.
    ///
    /// For nested changes, returns paths at each level.
    /// For example: `[["baz"], ["baz", "wombat"], ["baz", "wombat", "x"]]`
    ///
    /// Uses `Cow<'static, str>` to support both static field names (borrowed)
    /// and dynamic keys like HashMap keys or Vec indices (owned).
    fn paths(&self) -> Vec<Vec<Cow<'static, str>>>;

    /// Collects only the leaf (deepest) changed field paths.
    ///
    /// For example: `[["baz", "wombat", "x"]]` (not intermediate paths)
    ///
    /// Uses `Cow<'static, str>` to support both static field names (borrowed)
    /// and dynamic keys like HashMap keys or Vec indices (owned).
    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>>;
}

/// Change report for primitive types that have no nested fields.
///
/// Simply indicates whether the value changed or not.
#[derive(Clone, Debug, Default)]
pub struct PrimitiveChanged {
    /// Whether the primitive value changed.
    pub changed: bool,
}

impl PrimitiveChanged {
    /// Creates a new PrimitiveChanged indicating the value changed.
    pub fn new(changed: bool) -> Self {
        Self { changed }
    }
}

impl ChangeReport for PrimitiveChanged {
    fn any(&self) -> bool {
        self.changed
    }

    fn paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        if self.changed { vec![vec![]] } else { vec![] }
    }

    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        self.paths()
    }
}

// =============================================================================
// Field Cursor Trait
// =============================================================================

/// Trait for cursor types that cache ObjIds for O(1) change detection.
///
/// Cursors are generated for structs and cache the ObjId of each field.
/// When checking for changes, the cursor compares its cached ObjIds against
/// the document's current ObjIds, avoiding expensive value deserialization.
pub trait FieldCursor: Default + Clone + Debug {
    /// The associated change report type.
    type Changes: ChangeReport;

    /// Compares cached ObjIds against the document to detect changes.
    ///
    /// Returns a hierarchical change report indicating which fields changed.
    fn diff<D: ReadDoc>(&self, doc: &D, obj: &ObjId) -> Result<Self::Changes>;

    /// Refreshes the cached ObjIds from the document.
    ///
    /// Should be called after `update` to keep the cursor in sync.
    fn refresh<D: ReadDoc>(&mut self, doc: &D, obj: &ObjId) -> Result<()>;

    /// Checks if any cached ObjIds differ from the document.
    ///
    /// This is a fast O(field count) check.
    fn has_changes<D: ReadDoc>(&self, doc: &D, obj: &ObjId) -> Result<bool> {
        Ok(self.diff(doc, obj)?.any())
    }
}

/// Cursor for scalar/primitive types that don't have nested structure.
///
/// The ObjId passed to `diff()` and `refresh()` is the ObjId of the scalar
/// value itself (returned by `doc.get()`). When a scalar value is modified,
/// it gets a new ObjId, so comparing cached vs current ObjIds detects changes.
#[derive(Clone, Debug, Default)]
pub struct ScalarCursor {
    /// The cached ObjId for this scalar value.
    pub obj_id: Option<ObjId>,
}

impl FieldCursor for ScalarCursor {
    type Changes = PrimitiveChanged;

    fn diff<D: ReadDoc>(&self, _doc: &D, obj: &ObjId) -> Result<Self::Changes> {
        // The `obj` parameter is the current ObjId from doc.get().
        // Compare with our cached ObjId to detect changes.
        // If they differ, the value was modified.
        let changed = match &self.obj_id {
            Some(cached) => cached != obj,
            None => true, // No cached value means we weren't initialized properly
        };
        Ok(PrimitiveChanged::new(changed))
    }

    fn refresh<D: ReadDoc>(&mut self, _doc: &D, obj: &ObjId) -> Result<()> {
        // Cache the current ObjId so future diff() calls can compare against it
        self.obj_id = Some(obj.clone());
        Ok(())
    }
}

// =============================================================================
// Vec and Map Change Reports
// =============================================================================

/// Change report for `Vec<T>` fields.
///
/// Tracks which indices were added, removed, or modified.
#[derive(Clone, Debug, Default)]
pub struct VecChanges<C: ChangeReport> {
    /// Indices of newly added elements.
    pub added: Vec<usize>,
    /// Indices of removed elements (from previous state).
    pub removed: Vec<usize>,
    /// Modified elements with their nested change reports.
    pub modified: std::collections::HashMap<usize, C>,
}

impl<C: ChangeReport> ChangeReport for VecChanges<C> {
    fn any(&self) -> bool {
        !self.added.is_empty() || !self.removed.is_empty() || !self.modified.is_empty()
    }

    fn paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        let mut paths = Vec::new();

        // Report the collection itself changed if there are any changes
        if self.any() {
            paths.push(vec![]);
        }

        // Report added indices
        for idx in &self.added {
            paths.push(vec![Cow::Owned(idx.to_string())]);
        }

        // Report removed indices
        for idx in &self.removed {
            paths.push(vec![Cow::Owned(idx.to_string())]);
        }

        // Report modified indices and their nested paths
        for (idx, changes) in &self.modified {
            let idx_str: Cow<'static, str> = Cow::Owned(idx.to_string());
            paths.push(vec![idx_str.clone()]);
            for nested_path in changes.paths() {
                let mut full_path = vec![idx_str.clone()];
                full_path.extend(nested_path);
                paths.push(full_path);
            }
        }

        paths
    }

    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        let mut paths = Vec::new();

        // Added indices are leaf paths
        for idx in &self.added {
            paths.push(vec![Cow::Owned(idx.to_string())]);
        }

        // Removed indices are leaf paths
        for idx in &self.removed {
            paths.push(vec![Cow::Owned(idx.to_string())]);
        }

        // For modified, get the nested leaf paths
        for (idx, changes) in &self.modified {
            let idx_str: Cow<'static, str> = Cow::Owned(idx.to_string());
            let nested_leaves = changes.leaf_paths();
            if nested_leaves.is_empty() {
                // If no nested leaves, this index itself is the leaf
                paths.push(vec![idx_str]);
            } else {
                for nested_path in nested_leaves {
                    let mut full_path = vec![idx_str.clone()];
                    full_path.extend(nested_path);
                    paths.push(full_path);
                }
            }
        }

        // If nothing specific changed but collection changed, report empty path
        if paths.is_empty() && self.any() {
            paths.push(vec![]);
        }

        paths
    }
}

/// Change report for `HashMap<K, V>` fields.
///
/// Tracks which keys were added, removed, or modified.
#[derive(Clone, Debug, Default)]
pub struct MapChanges<K: Clone + Eq + Hash + Debug, C: ChangeReport> {
    /// Keys that were added.
    pub added: HashSet<K>,
    /// Keys that were removed.
    pub removed: HashSet<K>,
    /// Modified entries with their nested change reports.
    pub modified: std::collections::HashMap<K, C>,
}

impl<K: Clone + Eq + Hash + Debug + Default + ToString, C: ChangeReport> ChangeReport
    for MapChanges<K, C>
{
    fn any(&self) -> bool {
        !self.added.is_empty() || !self.removed.is_empty() || !self.modified.is_empty()
    }

    fn paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        let mut paths = Vec::new();

        // Report the collection itself changed if there are any changes
        if self.any() {
            paths.push(vec![]);
        }

        // Report added keys
        for key in &self.added {
            paths.push(vec![Cow::Owned(key.to_string())]);
        }

        // Report removed keys
        for key in &self.removed {
            paths.push(vec![Cow::Owned(key.to_string())]);
        }

        // Report modified keys and their nested paths
        for (key, changes) in &self.modified {
            let key_str: Cow<'static, str> = Cow::Owned(key.to_string());
            paths.push(vec![key_str.clone()]);
            for nested_path in changes.paths() {
                let mut full_path = vec![key_str.clone()];
                full_path.extend(nested_path);
                paths.push(full_path);
            }
        }

        paths
    }

    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        let mut paths = Vec::new();

        // Added keys are leaf paths
        for key in &self.added {
            paths.push(vec![Cow::<'static, str>::Owned(key.to_string())]);
        }

        // Removed keys are leaf paths
        for key in &self.removed {
            paths.push(vec![Cow::<'static, str>::Owned(key.to_string())]);
        }

        // For modified, get the nested leaf paths
        for (key, changes) in &self.modified {
            let key_str: Cow<'static, str> = Cow::Owned(key.to_string());
            let nested_leaves = changes.leaf_paths();
            if nested_leaves.is_empty() {
                // If no nested leaves, this key itself is the leaf
                paths.push(vec![key_str]);
            } else {
                for nested_path in nested_leaves {
                    let mut full_path = vec![key_str.clone()];
                    full_path.extend(nested_path);
                    paths.push(full_path);
                }
            }
        }

        // If nothing specific changed but collection changed, report empty path
        if paths.is_empty() && self.any() {
            paths.push(vec![]);
        }

        paths
    }
}

/// Change report for `Option<T>` fields.
///
/// Tracks whether the option presence changed and preserves inner change information.
#[derive(Clone, Debug, Default)]
pub enum OptionChanges<C: ChangeReport> {
    /// No change occurred.
    #[default]
    Unchanged,
    /// Changed from None to Some (value was added).
    BecameSome,
    /// Changed from Some to None (value was removed).
    BecameNone,
    /// Both were Some, contains the inner changes.
    Inner(C),
}

impl<C: ChangeReport> ChangeReport for OptionChanges<C> {
    fn any(&self) -> bool {
        match self {
            OptionChanges::Unchanged => false,
            OptionChanges::BecameSome => true,
            OptionChanges::BecameNone => true,
            OptionChanges::Inner(c) => c.any(),
        }
    }

    fn paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        match self {
            OptionChanges::Unchanged => vec![],
            OptionChanges::BecameSome | OptionChanges::BecameNone => vec![vec![]],
            OptionChanges::Inner(c) => c.paths(),
        }
    }

    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        match self {
            OptionChanges::Unchanged => vec![],
            OptionChanges::BecameSome | OptionChanges::BecameNone => vec![vec![]],
            OptionChanges::Inner(c) => c.leaf_paths(),
        }
    }
}

impl<C: ChangeReport> OptionChanges<C> {
    /// Returns true if the option became Some (was None before).
    pub fn became_some(&self) -> bool {
        matches!(self, OptionChanges::BecameSome)
    }

    /// Returns true if the option became None (was Some before).
    pub fn became_none(&self) -> bool {
        matches!(self, OptionChanges::BecameNone)
    }

    /// Returns the inner changes if both values were Some.
    pub fn inner(&self) -> Option<&C> {
        match self {
            OptionChanges::Inner(c) => Some(c),
            _ => None,
        }
    }
}

/// Change report for `Result<T, E>` fields.
///
/// Tracks whether the result variant changed and preserves inner change information.
#[derive(Clone, Debug, Default)]
pub enum ResultChanges<OkC: ChangeReport, ErrC: ChangeReport> {
    /// No change occurred.
    #[default]
    Unchanged,
    /// Variant changed from Err to Ok.
    BecameOk,
    /// Variant changed from Ok to Err.
    BecameErr,
    /// Both were Ok, contains the inner Ok changes.
    OkInner(OkC),
    /// Both were Err, contains the inner Err changes.
    ErrInner(ErrC),
}

impl<OkC: ChangeReport, ErrC: ChangeReport> ChangeReport for ResultChanges<OkC, ErrC> {
    fn any(&self) -> bool {
        match self {
            ResultChanges::Unchanged => false,
            ResultChanges::BecameOk => true,
            ResultChanges::BecameErr => true,
            ResultChanges::OkInner(c) => c.any(),
            ResultChanges::ErrInner(c) => c.any(),
        }
    }

    fn paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        match self {
            ResultChanges::Unchanged => vec![],
            ResultChanges::BecameOk | ResultChanges::BecameErr => vec![vec![]],
            ResultChanges::OkInner(c) => c.paths(),
            ResultChanges::ErrInner(c) => c.paths(),
        }
    }

    fn leaf_paths(&self) -> Vec<Vec<Cow<'static, str>>> {
        match self {
            ResultChanges::Unchanged => vec![],
            ResultChanges::BecameOk | ResultChanges::BecameErr => vec![vec![]],
            ResultChanges::OkInner(c) => c.leaf_paths(),
            ResultChanges::ErrInner(c) => c.leaf_paths(),
        }
    }
}

impl<OkC: ChangeReport, ErrC: ChangeReport> ResultChanges<OkC, ErrC> {
    /// Returns true if the result became Ok (was Err before).
    pub fn became_ok(&self) -> bool {
        matches!(self, ResultChanges::BecameOk)
    }

    /// Returns true if the result became Err (was Ok before).
    pub fn became_err(&self) -> bool {
        matches!(self, ResultChanges::BecameErr)
    }

    /// Returns the inner Ok changes if both values were Ok.
    pub fn ok_inner(&self) -> Option<&OkC> {
        match self {
            ResultChanges::OkInner(c) => Some(c),
            _ => None,
        }
    }

    /// Returns the inner Err changes if both values were Err.
    pub fn err_inner(&self) -> Option<&ErrC> {
        match self {
            ResultChanges::ErrInner(c) => Some(c),
            _ => None,
        }
    }
}

// =============================================================================
// Vec and Map Cursors
// =============================================================================

/// Cursor for `Vec<T>` fields.
#[derive(Clone, Debug, Default)]
pub struct VecCursor<C: FieldCursor> {
    /// ObjId of the list object itself.
    pub list_id: Option<ObjId>,
    /// Number of elements when last refreshed.
    pub len: usize,
    /// Cursors for each element.
    pub elements: Vec<C>,
}

impl<C: FieldCursor> FieldCursor for VecCursor<C> {
    type Changes = VecChanges<C::Changes>;

    fn diff<D: ReadDoc>(&self, doc: &D, obj: &ObjId) -> Result<Self::Changes> {
        let mut changes = VecChanges::default();

        let current_len = doc.length(obj);

        // Check for added elements
        if current_len > self.len {
            changes.added = (self.len..current_len).collect();
        }

        // Check for removed elements
        if current_len < self.len {
            changes.removed = (current_len..self.len).collect();
        }

        // Check for modified elements (for elements that exist in both)
        let check_len = std::cmp::min(current_len, self.len);
        for idx in 0..check_len {
            if idx < self.elements.len() {
                // Get the current ObjId for this element
                if let Some((_, element_obj_id)) = doc.get(obj, idx)? {
                    let element_changes = self.elements[idx].diff(doc, &element_obj_id)?;
                    if element_changes.any() {
                        changes.modified.insert(idx, element_changes);
                    }
                }
            }
        }

        Ok(changes)
    }

    fn refresh<D: ReadDoc>(&mut self, doc: &D, obj: &ObjId) -> Result<()> {
        let new_len = doc.length(obj);
        self.list_id = Some(obj.clone());

        // Resize element cursors to match document length
        self.elements.resize_with(new_len, C::default);

        // Refresh each element cursor
        for idx in 0..new_len {
            if let Some((_, element_obj_id)) = doc.get(obj, idx)? {
                self.elements[idx].refresh(doc, &element_obj_id)?;
            }
        }

        self.len = new_len;
        Ok(())
    }
}

/// Cursor for `HashMap<K, V>` fields.
#[derive(Clone, Debug, Default)]
pub struct MapCursor<C: FieldCursor> {
    /// ObjId of the map object itself.
    pub map_id: Option<ObjId>,
    /// Cursors keyed by map key.
    pub entries: std::collections::HashMap<String, C>,
}

impl<C: FieldCursor> FieldCursor for MapCursor<C> {
    type Changes = MapChanges<String, C::Changes>;

    fn diff<D: ReadDoc>(&self, doc: &D, obj: &ObjId) -> Result<Self::Changes> {
        let mut changes = MapChanges::default();

        let current_keys: HashSet<String> = doc.keys(obj).collect();

        // Find added keys (in current but not in entries)
        for key in &current_keys {
            if !self.entries.contains_key(key) {
                changes.added.insert(key.clone());
            }
        }

        // Find removed keys (in entries but not in current)
        for key in self.entries.keys() {
            if !current_keys.contains(key) {
                changes.removed.insert(key.clone());
            }
        }

        // Check modified entries (keys that exist in both)
        for (key, cursor) in &self.entries {
            if current_keys.contains(key) {
                // Get the current ObjId for this entry
                if let Some((_, entry_obj_id)) = doc.get(obj, key.as_str())? {
                    let entry_changes = cursor.diff(doc, &entry_obj_id)?;
                    if entry_changes.any() {
                        changes.modified.insert(key.clone(), entry_changes);
                    }
                }
            }
        }

        Ok(changes)
    }

    fn refresh<D: ReadDoc>(&mut self, doc: &D, obj: &ObjId) -> Result<()> {
        self.map_id = Some(obj.clone());
        let current_keys: HashSet<String> = doc.keys(obj).collect();

        // Remove entries for keys that no longer exist
        self.entries.retain(|k, _| current_keys.contains(k));

        // Refresh existing entries and add new ones
        for key in current_keys {
            if let Some((_, entry_obj_id)) = doc.get(obj, key.as_str())? {
                let cursor = self.entries.entry(key).or_default();
                cursor.refresh(doc, &entry_obj_id)?;
            }
        }

        Ok(())
    }
}

// =============================================================================
// Tracked<T> Wrapper
// =============================================================================

/// A value loaded from an Automerge document with change tracking.
///
/// `Tracked<T>` wraps a value and remembers where it was loaded from,
/// allowing you to detect when the document has been modified and efficiently
/// update your local copy.
///
/// # Change Detection Methods
///
/// `Tracked<T>` provides two methods for detecting changes:
///
/// - **`has_changes()`** - Detects ALL changes by comparing actual values (O(data size))
/// - **`has_object_changes()`** - Detects changes via cached ObjId comparison (O(field count))
///
/// Both methods are accurate, but `has_object_changes()` is faster for large structs
/// because it compares cached ObjIds without deserializing values.
///
/// # How Change Detection Works
///
/// Automerge assigns unique ObjIds to all values (scalars and objects). When a value
/// is modified, it gets a new ObjId. `Tracked<T>` caches ObjIds from when the value
/// was loaded and compares them against current ObjIds for O(1) per-field change detection.
///
/// # Recommended Usage
///
/// **For quick checks:** Use `has_object_changes()` as a fast filter before updating.
///
/// ```rust
/// # use automorph::{Automorph, Tracked, ChangeReport};
/// # use automerge::{AutoCommit, ROOT};
/// # #[derive(Automorph, Clone, Debug, Default)]
/// # struct Data { items: Vec<String> }
/// # fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let mut doc = AutoCommit::new();
/// # let data = Data { items: vec!["a".to_string()] };
/// # data.save(&mut doc, &ROOT, "data")?;
/// # let mut tracked = Tracked::<Data>::load(&doc, &ROOT, "data")?;
/// // Pattern 1: Quick filter then full check
/// if tracked.has_object_changes(&doc)? {
///     let changes = tracked.update(&doc)?;
///     // changes is accurate
/// }
///
/// // Pattern 2: Always update (SAFEST)
/// let changes = tracked.update(&doc)?;
/// if changes.any() {
///     // Handle changes
/// }
/// # Ok(())
/// # }
/// ```
///
/// # Performance
///
/// | Operation | Complexity | Description |
/// |-----------|------------|-------------|
/// | `has_changes()` | O(data size) | Full value comparison, always accurate |
/// | `has_object_changes()` | O(field count) | ObjId comparison, fast and accurate |
/// | `update()` | O(data size) | 100% accurate, refreshes cached state |
/// | `save()` | O(changed data size) | Only writes changed fields |
#[derive(Clone, Debug)]
pub struct Tracked<T: Automorph> {
    /// The actual value.
    value: T,
    /// Cached ObjIds for each field (mirrors struct hierarchy).
    cursor: T::Cursor,
    /// The document location this was loaded from.
    obj: ObjId,
    /// The property this was loaded from.
    prop: Prop,
}

impl<T: Automorph> Tracked<T> {
    /// Loads a value from the document and caches its field ObjIds.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID
    /// * `prop` - The property name or index
    ///
    /// # Errors
    ///
    /// Returns an error if the value cannot be loaded.
    pub fn load<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
    ) -> Result<Self> {
        let obj = obj.as_ref().clone();
        let prop: Prop = prop.into();

        let value = T::load(doc, &obj, prop.clone())?;
        let mut cursor = T::Cursor::default();

        // Get the ObjId for this value and refresh the cursor
        if let Some((_, value_obj_id)) = doc.get(&obj, prop.clone())? {
            cursor.refresh(doc, &value_obj_id)?;
        }

        Ok(Self {
            value,
            cursor,
            obj,
            prop,
        })
    }

    /// Loads a value from a specific document version and caches its field ObjIds.
    ///
    /// # Arguments
    ///
    /// * `doc` - The Automerge document to read from
    /// * `obj` - The parent object ID
    /// * `prop` - The property name or index
    /// * `heads` - The change hashes representing the document version
    ///
    /// # Errors
    ///
    /// Returns an error if the value cannot be loaded.
    pub fn load_at<D: ReadDoc>(
        doc: &D,
        obj: impl AsRef<ObjId>,
        prop: impl Into<Prop>,
        heads: &[ChangeHash],
    ) -> Result<Self> {
        let obj = obj.as_ref().clone();
        let prop: Prop = prop.into();

        let value = T::load_at(doc, &obj, prop.clone(), heads)?;
        let mut cursor = T::Cursor::default();

        // Get the ObjId for this value and refresh the cursor
        if let Some((_, value_obj_id)) = doc.get_at(&obj, prop.clone(), heads)? {
            cursor.refresh(doc, &value_obj_id)?;
        }

        Ok(Self {
            value,
            cursor,
            obj,
            prop,
        })
    }

    /// Checks if the document has any changes compared to this tracked value.
    ///
    /// This method detects **ALL** changes including:
    /// - Structural changes (nested objects, collections)
    /// - Scalar field changes (String, integers, bools)
    /// - Option<T> transitions (None ↔ Some)
    /// - Result<T,E> transitions (Ok ↔ Err)
    ///
    /// # Performance
    ///
    /// This is O(data size) - it loads and compares the full value.
    /// For a faster O(field count) check that only detects structural changes,
    /// use [`has_object_changes()`](Self::has_object_changes).
    ///
    /// # Example
    ///
    /// ```rust
    /// use automorph::{Automorph, Tracked};
    /// use automerge::{AutoCommit, ROOT};
    ///
    /// #[derive(Automorph, Clone, Debug, Default)]
    /// struct Person {
    ///     name: String,
    ///     age: u32,
    /// }
    ///
    /// let mut doc = AutoCommit::new();
    /// let person = Person { name: "Alice".to_string(), age: 30 };
    /// person.save(&mut doc, &ROOT, "person").unwrap();
    ///
    /// let mut tracked = Tracked::<Person>::load(&doc, &ROOT, "person").unwrap();
    ///
    /// // Modify only a scalar field
    /// let person2 = Person { name: "Bob".to_string(), age: 30 };
    /// person2.save(&mut doc, &ROOT, "person").unwrap();
    ///
    /// // has_changes detects the name change
    /// assert!(tracked.has_changes(&doc).unwrap());
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if the document cannot be read.
    ///
    /// # See Also
    ///
    /// - [`has_object_changes()`](Self::has_object_changes) - Faster but only detects structural changes
    /// - [`update()`](Self::update) - Updates the value and returns detailed changes
    pub fn has_changes<D: ReadDoc>(&self, doc: &D) -> Result<bool> {
        let changes = self.value.diff(doc, &self.obj, self.prop.clone())?;
        Ok(changes.any())
    }

    /// Checks if the document has structural (object-level) changes.
    ///
    /// This detects changes to nested objects (structs, Vecs, HashMaps) but
    /// NOT changes to scalar fields (String, numbers, bools) within structs.
    ///
    /// # Performance
    ///
    /// This is O(field count) - it compares cached ObjIds without deserializing values.
    ///
    /// # When to Use
    ///
    /// Use this as a performance optimization when you only care about structural changes.
    /// For reliable change detection of all fields, use [`has_changes()`](Self::has_changes).
    ///
    /// # Example
    ///
    /// ```rust
    /// use automorph::{Automorph, Tracked};
    /// use automerge::{AutoCommit, ROOT};
    ///
    /// #[derive(Automorph, Clone, Debug, Default)]
    /// struct Container {
    ///     items: Vec<String>,
    /// }
    ///
    /// let mut doc = AutoCommit::new();
    /// let container = Container { items: vec!["a".to_string()] };
    /// container.save(&mut doc, &ROOT, "container").unwrap();
    ///
    /// let mut tracked = Tracked::<Container>::load(&doc, &ROOT, "container").unwrap();
    ///
    /// // Adding an item is a structural change
    /// let container2 = Container { items: vec!["a".to_string(), "b".to_string()] };
    /// container2.save(&mut doc, &ROOT, "container").unwrap();
    ///
    /// assert!(tracked.has_object_changes(&doc).unwrap());
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if the document cannot be read.
    ///
    /// # See Also
    ///
    /// - [`has_changes()`](Self::has_changes) - Detects ALL changes (slower but complete)
    /// - [`cursor_diff()`](Self::cursor_diff) - Returns detailed structural change information
    pub fn has_object_changes<D: ReadDoc>(&self, doc: &D) -> Result<bool> {
        if let Some((_, value_obj_id)) = doc.get(&self.obj, self.prop.clone())? {
            self.cursor.has_changes(doc, &value_obj_id)
        } else {
            // Value was deleted
            Ok(true)
        }
    }

    /// Deprecated: Use [`has_object_changes()`](Self::has_object_changes) or [`has_changes()`](Self::has_changes).
    ///
    /// # Deprecation Notice
    ///
    /// This method has been renamed to `has_object_changes()` to clarify that it
    /// only detects structural (object-level) changes, not scalar field changes.
    ///
    /// For detecting ALL changes including scalars, use [`has_changes()`](Self::has_changes).
    #[deprecated(
        since = "0.2.0",
        note = "Renamed to has_object_changes() for clarity. For full change detection, use has_changes()."
    )]
    pub fn has_structural_changes<D: ReadDoc>(&self, doc: &D) -> Result<bool> {
        self.has_object_changes(doc)
    }

    /// Deprecated: Use [`has_object_changes()`](Self::has_object_changes) instead.
    #[deprecated(
        since = "0.2.0",
        note = "Renamed to has_object_changes() to clarify that it only detects structural changes (nested objects), not scalar field changes."
    )]
    pub fn might_have_changes<D: ReadDoc>(&self, doc: &D) -> Result<bool> {
        self.has_object_changes(doc)
    }

    /// Gets a detailed hierarchical change report based on ObjId comparison.
    ///
    /// # ⚠️ WARNING: Only Detects Structural Changes!
    ///
    /// Like [`has_structural_changes()`](Self::has_structural_changes), this method compares ObjIds,
    /// not actual values. It may report no changes even when scalar fields
    /// have been modified.
    ///
    /// **For reliable change detection, use [`update()`](Self::update) instead.**
    ///
    /// # Performance
    ///
    /// This is an O(field count) operation that compares cached ObjIds,
    /// returning a detailed report of which fields changed.
    ///
    /// # Errors
    ///
    /// Returns an error if the document cannot be read.
    pub fn cursor_diff<D: ReadDoc>(&self, doc: &D) -> Result<<T::Cursor as FieldCursor>::Changes> {
        if let Some((_, value_obj_id)) = doc.get(&self.obj, self.prop.clone())? {
            self.cursor.diff(doc, &value_obj_id)
        } else {
            // Value was deleted - report as fully changed
            Ok(<T::Cursor as FieldCursor>::Changes::default())
        }
    }

    /// Updates the value from the document and returns a change report.
    ///
    /// This method walks each field individually and only updates fields that
    /// have actually changed. It does NOT call `load()`.
    ///
    /// This also refreshes the cached ObjIds for future comparisons.
    ///
    /// # Errors
    ///
    /// Returns an error if the update fails.
    pub fn update<D: ReadDoc>(&mut self, doc: &D) -> Result<T::Changes> {
        // Update the value field-by-field (does NOT call load)
        let changes = self.value.update(doc, &self.obj, self.prop.clone())?;

        // Refresh the cursor
        if let Some((_, value_obj_id)) = doc.get(&self.obj, self.prop.clone())? {
            self.cursor.refresh(doc, &value_obj_id)?;
        }

        Ok(changes)
    }

    /// Saves changes back to the document.
    ///
    /// # Errors
    ///
    /// Returns an error if the save operation fails.
    pub fn save<D: Transactable + ReadDoc>(&self, doc: &mut D) -> Result<()> {
        self.value.save(doc, &self.obj, self.prop.clone())
    }

    /// Returns a reference to the inner value.
    pub fn get(&self) -> &T {
        &self.value
    }

    /// Returns a mutable reference to the inner value.
    ///
    /// Note: After modifying the value, you should call `save` to persist
    /// changes to the document.
    pub fn get_mut(&mut self) -> &mut T {
        &mut self.value
    }

    /// Consumes the wrapper and returns the inner value.
    pub fn into_inner(self) -> T {
        self.value
    }
}

impl<T: Automorph> Deref for Tracked<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}

impl<T: Automorph + Default> Default for Tracked<T> {
    fn default() -> Self {
        Self {
            value: T::default(),
            cursor: T::Cursor::default(),
            obj: automerge::ROOT,
            prop: Prop::Map(String::new()),
        }
    }
}