HolonSpace Design Spec

Introduction

This document specifies the design for the HolonSpace component of the MAP. HolonSpaces are AgentSpaces that store and provide access to information about Holons and HolonRelationships within the membrane of that AgentSpace.

Foundational Concepts

HolonSpaces are based on the Holons Holochain Zome that consists of the Holon EntryType and the SmartLink LinkType. Effectively, these can be thought of as the nodes and links of a graph database. Holons and SmartLinks reference and rely on MAP Descriptors that are managed in shared Metaspaces. A HolonSpace can store any information that can be described by MAP Descriptors. MAP Metaspaces allow the set MAP Descriptors to be extended in real-time without having to recompile or redeploy a HolonSpace. A MAP Query Engine supports execution of fairly rich queries on top of the holochain storage layer.

Holon EntryType

MAP Holons are self-describing, active subjects. The HolonDescriptor for a Holon type specifies the set of properties that each instance of that Holon type stores, the set of relationships instances can participate in, and the set of affordances that Holons of that type afford. To conserve space, Holon's only reference (rather than store) their HolonDescriptors.

pub struct Holon {
    descriptor: HolonReference, // a reference to (a specific version of) the HolonDescriptor that describes this Holon and its properties, relationships, and actions   
    properties: PropertyMap, // values for the scalar properties of this holon
    relationships: RelationshipMap, // a map of all of the relationships originating from this Holon 
    affordances: AffordanceMap, // the set of affordance (invokable actions) offered by this Holon in its current state
}

Holon Properties

Property values are stored in a PropertyMap within the Holon EntryType.

pub struct PropertyMap {
    properties: BTreeMap<String,PropertyValue> // where the key is the `name` of that property
}

Values for each of Holon's properties are represented via the PropertyValue enum. Each MAP property type has a BaseValueType that determines how values of that property type will be represented in a given language binding. A small set of BaseValueTypes is supported in the prototype. The number of supported BaseValueTypes will grow as the MAP evolves.

pub enum PropertyValue {
    StringValue(StringValue),
    BooleanValue(bool),
    IntegerValue(i64),
    AnyLinkableHash(AnyLinkableHash),
    ActionHash(ActionHash),
    EntryHash(EntryHash),
}

HolonRelationships

Holons are related to each other via holon relationships. The RelationshipDescriptor specifies a source HolonType and a target HolonType for the relationship.

Holon relationships support a variety of cardinalities (e.g., 1-to-many, 0-to-many, many-to-many, etc.) and association semantics (e.g., Composite, Aggregate, Association). Since, in general, the target of a relationship might have many values, the result of navigating a relationship is represented as a collection of HolonReferences. For a 1-to-1 relationship, that collection will just contain a single reference.

MAP Query Engine

The MAP Query Engine provides a query execution layer on top of the holochain storage layer. Specifically, it supports filtered relationship navigation using a simplified graph database query language (initially Open CypherOpen Cypher).

SmartLinks Layer

• Manages creation and deletion of SmartLinks

• Creates 1 SmartLink for each defined _access_path_spec for a role_name of a relationship.

• Encodes various information in the tag field of a holochain Link, to support prefix filtering by get_links() and SmartLink filtering and sorting of the retrieved links in a way that minimizes the need to retrieve the associated Holon.

• Specifically,

  • put role_name and access_path_name at the beginning of the content field (prolog), to allow idk get_links() prefix filtering. This will return a vector of SmartLinks consisting of only those links associated with the specified base_holon, for a specified access_path for a relationship role_name.
  • AFTER the prolog, encode null-separated values for each of the properties specified in the access_path.

The layer ABOVE the SmartLinks layer can then perform filtering and sorting (and pagination) on the "suffix" of the SmartLink's content field. Note that the extra entry is not really required, since I have access to the actual Holon via its ActionHash if I need to access more of its fields than will fit in the SmartLink's content field. Some sort of flag should be included to indicate when values were too long to fit into content.

Holochain Storage Layer

This layer provides persistent storage functions for instances of Holon EntryTypes and SmartLink LinkTypes. It also supports retrieval of a Vec The holochain get_links() function(input: GetLinksInput) -> ExternResult<Vec>](https://github.com/holochain/holochain/blob/develop/crates/hdk/src/link.rs) provides retrieval of a Vec<

Use get_link prefixes to select the desired relationship, role_name, and access_path.

• The remainder of the tag content can be used to store null separated property_values. The sequence of property_values to store is specified by the access_path.

pub struct AccessPathSpec {
    relationship_descriptor: HolonReference,
    role_name: String,
    filter_spec: FilterSpec,

    
}


get_related_holons(from_holon: HolonReference, using_access_path: AccessPath) -> ExternResult<Vec<Record>>. The Records returned are HolonReferences.

Holon Zome Functions

Relationships between Holons are realized via SmartLinks. A SmartLink is a holochain LinkType structured to facilitate associative query resolution of a relationship without requiring linked entries to be retrieved. The concept and design of SmartLinks was inspired by the TrustAtom concept pioneered within the TrustGraph project. SmartLinks allow the MAP to support bi-directional navigation of any relationship. They also lay the foundation for supporting filtered and (eventually) ordered and paginated result sets.

See the SmartLinks Design Spec for more info.

It is assumed that HolonDescriptors (and the PropertyDescriptors, ActionDescriptors, and RelationshipDescriptors they rely on) will be cached, using their HolonId as their key. The caching design is described here: (TODO: add wiki for caching design).