//! Heap 产生、Store/VM 取走、宿主缓存消费的变更通知数据；不保存对象所有权。
//! 通知反映已提交的修改，不是可重放操作日志，也不保证消费时源对象仍存活。

use crate::ObjectRef;

/// Heap::record_change 用于合并通知的键；同一对象的不同属性仍各自保留。
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum ChangeKey {
    /// Heap 属性写入/删除发布具体字段名；消费者可只失效对应字段的观察。
    Attribute(String),
    /// 载荷替换、类型附着或共享引用更新改变整体内容；消费者按内容依赖处理。
    Contents,
}

/// Heap::take_changes 从内部有序映射生成的单条合并通知，供宿主失效缓存。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ObjectChange {
    /// 修改来源的完整借用身份，包含代际；不能当作有效拥有根直接使用。
    pub object: ObjectRef,
    /// 被修改的字段或整体载荷类别。
    pub key: ChangeKey,
    /// 此对象/键在本批最后一次通知的对象版本，不是批次序号。
    pub version: u64,
}

/// Store::take_changes 返回上次取走后累计的合并结果；取走时重置内部批次。
/// 溢出会丢弃精确条目并要求全面重验，消费者不能把空 changes 解释为没有修改。
#[derive(Debug, Default)]
pub struct ChangeBatch {
    /// 精确通知；同一对象/键重复修改仅保留最新版本，排序不表示实际修改先后。
    pub changes: Vec<ObjectChange>,
    /// true 时须全面重验所持依赖，不能仅处理 changes 中的对象。
    pub rescan_required: bool,
}

/// Heap::record_change 的唯一对象/键数量上限；更新已有键不额外占用容量。
pub(crate) const MAX_PENDING_CHANGES: usize = 4096;