Holon Caching

[evomimic]

Summary

This discussion focuses on the design for holon caching strategies on both the client-side (TypeScript) and guest-side (Rust) components of the MAP architecture. Note that caching is only employed for previously committed Holons. Holons being staged for commit are handled separately.

Caching Requirements

1. Minimize storage requirements by holding only a single copy of a Holon in memory and limit cloning
2. Support both client-side and guest-side caching
3. Independent caches -- the client-side and guest-side have different access patterns, so each side should be able to make its own decisions regarding which holons to cache.
4. On the guest-side, transparently handle retrieving holons from local or external spaces based on their HolonId
5. Avoid the (time) cost of retrieving a holon multiple times from the persistent store or an external space by retrieving it, at most, once and then caching it
6. Support "lazy load" of related holons -- incrementally populate the relationship_map for a holon on demand (i.e., only when asked for).
7. Avoid the cost of expanding a relationship multiple times from the persistent store or external space

Design Challenges

This section describes various design challenges associated with meeting the caching requirements.

Handling Local and External Holon Ids

Background

A HolonId can either be Local or External:

pub enum HolonId {
    Local(LocalId),
    External(ExternalId),
}

/// The `LocalId` is the `ActionHash` of a specific version of a Holon within the Local HolonSpace
pub struct LocalId(pub ActionHash);

/// The ```HolonSpaceId``` is the ActionHash of the HolonSpaceProxy within the Local Holon Space for an external HolonSpace that 
pub struct HolonSpaceId(pub ActionHash);

pub struct ExternalId {
    pub space_id: HolonSpaceId,
    pub local_id: LocalId,
}

Each HolonSpace has its own LocalSpaceManager. The LocalSpaceManager owns a LocalCacheManager and zero or more ExternalSpaceManagers, each with their own ExternalCacheManager. Local Holons are cached by the LocalCacheManager, external Holons are cached by the ExternalCacheManager owned by the ExternalSpaceManager associated with their space_id.
The LocalSpaceManager offers a get_rc_holon method for getting access to a cached holon. Retrieving a Holon involves first determining which space manager is responsible for caching that Holon based on its HolonId.

The Challenge

Cache misses for LocalIds are resolved by the local CacheManager by fetching the Holon from the local persistent store (using a Persistence Layer method). Cache misses for ExternalIds are resolved by the OutboundSpaceProxy's CacheManager invoking a fetch_holon dance on the HolonSpace that owns the holon (via a Dance Layer method). This creates a dependency challenge since the Dance Layer is "above" (and therefore has a dependency on) the Shared Objects layer.

Proposal

Unified Holon Access

Define a HolonCacheAccess trait in the Shared Objects Layer that provides a single entry-point method for holon retrieval:

fn get_rc_holon(&self, id: HolonId) -> Result<Rc<RefCell<Holon>>, HolonError>

The get_rc_holon method provides shared ownership of a potentially mutable, cached holon, enabling efficient reuse and incremental loading of its data. If the requested holon is in the cache, it returns the cached instance. Otherwise, it resolves the holon (locally or externally), caches it, and then returns it. The return type of Rc<RefCell<Holon>> ensures:

1. Shared Ownership: multiple components can share access to the same holon instance
2. Interior Mutability: so that the holon can be modified (e.g., to support lazy loading of relationships) without requiring exclusive ownership or cloning.

HolonResolver

When the get_rc_holon method encounters a cache miss (i.e., it cannot find the desired holon in its cache) it needs to resolve the cache miss. This design applies the Strategy Design Pattern to resolve the cache miss in a way that preserves the dependency requirements of the MAP Holons architecture:

dance_layer -> reference_layer -> shared_objects_layer -> persistence_layer

The following trait is defined in the Shared Objects Layer:

pub trait HolonResolver {
    /// Resolves a holon identified by its LocalId.
    fn resolve_holon(local_id: &LocalId) -> Result<Holon, HolonError>;
}

Implementations of this trait encapsulate different strategies for fetching the holon based on its LocalId.

The LocalPersistenceResolver defined in the Shared Objects layer handles resolution of holons stored locally (backed by persistence layer functions).

pub struct LocalHolonResolver;

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

impl HolonResolver for LocalHolonResolver {
    fn resolve_holon(&self, local_id: &LocalId) -> Result<Holon, HolonError> {
        // Logic to resolve a local holon from the persistence layer
        
    }
}

The ExternalDanceResolver defined in the Dance layer handles resolution of holons in external spaces by invoking a fetch_holon dance on the external space.

pub struct ExternalHolonResolver {
    space_id: HolonSpaceId,
}

impl ExternalHolonResolver {
    pub fn new(space_id: HolonSpaceId) -> Self {
        Self { space_id }
    }
}

impl HolonResolver for ExternalHolonResolver {
    fn resolve_holon(&self, local_id: &LocalId) -> Result<Holon, HolonError> {
        // Logic to resolve an external holon via a `fetch_holon ` dance
        
    }
}

Holon Cache Manager

Caching of holons is handled by a HolonCacheManager that has been injected with a HolonResolver trait object.

pub struct CacheManager {
    cache: HolonCache,
    resolver: Box<dyn HolonResolver>, // Injected resolver
}

impl CacheManager {
    pub fn new(resolver: Box<dyn HolonResolver>) -> Self {
        Self {
            cache: HolonCache::new(100),
            resolver,
        }
    }

    pub fn get_rc_holon(&self, local_id: &LocalId) -> Result<Rc<RefCell<Holon>>, HolonError> {
        if let Some(holon) = self.cache.get(local_id) {
            return Ok(holon.clone());
        }

        // Cache miss: Resolve the holon
        let holon = self.resolver.resolve_holon(local_id)?;
        let rc_holon = Rc::new(RefCell::new(holon));
        self.cache.put(local_id.clone(), rc_holon.clone());

        Ok(rc_holon)
    }
}

HolonSpaceManager

The HolonSpaceManager coordinates local and outbound interactions, maintaining references to both its local_cache_manager and its outbound_space_proxies .

pub struct HolonSpaceManager {
    space_holon: Option<HolonReference>,
    local_cache_manager: LocalCacheManager,
    outbound_space_proxies: HashMap<HolonSpaceId, OutboundSpaceProxy>,
    nursery: Rc<RefCell<Nursery>>,
}

impl HolonSpaceManager {
    pub fn new(
        local_cache_manager: LocalCacheManager,
        outbound_space_proxies: HashMap<HolonSpaceId, OutboundSpaceProxy>,
    ) -> Self {
        Self {
            local_cache_manager,
            outbound_space_proxies,
        }
    }

    /// Retrieves a Holon based on its HolonId.
    /// Delegates to the appropriate cache manager or proxy.
    pub fn get_rc_holon(&self, holon_id: &HolonId) -> Result<Rc<RefCell<Holon>>, HolonError> {
        match holon_id {
            HolonId::Local(local_id) => self.local_cache_manager.get_rc_holon(local_id),
            HolonId::External(external_id) => {
                if let Some(proxy) = self.outbound_space_proxies.get(&external_id.space_id) {
                    proxy.get_rc_holon(&external_id.local_id)
                } else {
                    Err(HolonError::UnknownExternalSpace)
                }
            }
        }
    }

    /// Registers a new outbound space proxy.
    pub fn add_outbound_space_proxy(&mut self, proxy: OutboundSpaceProxy) {
        self.outbound_space_proxies.insert(proxy.space_id.clone(), proxy);
    }
}

Outbound Space Proxy

The OutboundSpaceProxy caches external holons and handles outbound requests to external spaces, including resolving holons through external dances.

pub struct OutboundSpaceProxy {
    space_id: HolonSpaceId,
    external_cache_manager: CacheManager,
}

impl OutboundSpaceProxy {
    pub fn new(space_id: HolonSpaceId, resolver: Box<dyn HolonResolver>) -> Self {
        Self {
            space_id,
            external_cache_manager: CacheManager::new(resolver),
        }
    }

    pub fn get_rc_holon(&self, local_id: &LocalId) -> Result<Rc<RefCell<Holon>>, HolonError> {
        self.external_cache_manager.get_rc_holon(local_id)
    }
}

Initializing the HolonSpaceManager

The HolonSpaceManager needs to be configured with ExternalHolonResolvers for each of its OutboundSpaceProxies. Since these resolvers are defined in the DanceLayer, HolonSpaceManager initialization needs to be initiated from the Dance layer.

impl HolonSpaceManager {
    /// Initializes the `HolonSpaceManager` with only staged holons, external proxies, and the space reference.
    pub fn init(
        staged_holons: Vec<Rc<RefCell<Holon>>>,              // Staged holons for the nursery
        keyed_index: BTreeMap<MapString, usize>,             // Keyed index for staged holons
        space_holon_ref: Option<HolonReference>,             // Reference to the current space holon
        outbound_space_proxies: HashMap<HolonSpaceId, OutboundSpaceProxy>, // External space proxies
    ) -> Self {
        // Initialize the nursery with staged holons and keyed index
        let nursery = Rc::new(RefCell::new(Nursery::new_from_stage(
            staged_holons,
            keyed_index,
        )));

        // Initialize the local cache manager with a LocalHolonResolver
        let local_resolver = Box::new(LocalHolonResolver::new());
        let local_cache_manager = CacheManager::new(local_resolver);

        // Create and return the `HolonSpaceManager`
        HolonSpaceManager {
            space_holon: space_holon_ref,
            local_cache_manager,
            outbound_space_proxies,
            nursery,
        }
    }
}

The details of how the Dance layer can determine the set of OutboundSpaceProxies to initialize will be explored in a later discussion specifically focused on interactions between Holon Spaces.

Interactions

Impacts

To realize the design presented here requires the following enhancements:

Shared Objects Layer

API changes

In the shared_objects/api module:

• Define a HolonCacheAccess trait with a single method:
  fn get_rc_holon(&self, holon_id: &HolonId)-> Result<Rc<RefCell<Holon>>, HolonError>

• Delete HolonCacheBehavior trait in space_manager.rs

• Define HolonResolver in

THIS SECTION STILL NEEDS TO BE ADDED