Implement AddRelatedHolons Dance (Undescribed)

Summary

This enhancement adds the "_add_related_holons_" dance to the Uniform API. This dance adds one or more staged or existing holons to a named, but undescribed, relationship target of a staged_holon (source). If an entry for relationship_name is not already present in the source holon's relationship_map, this function adds one.

Current State:

The holons zome already includes a native add_related_holons method in the staged_reference.rs file:

pub fn add_related_holons(
    &self, 
    context: &mut HolonsContext, 
    relationship_name: RelationshipName, 
    holons: Vec<HolonReference>, 
) -> Result<(), HolonError>

In this method,

self is the StagedReference that refers to the holon that is the source of the relationship,
relationship_name indicates which of the relationships in the source's relationship map the holons are to be added for. In the future, this parameter will be replaced with a reference to the RelationshipDescriptor for this relationship
holons is a list of HolonReferences to staged or existing holons that are to be added to the target collection for this relationship.

Proposal

Native Function

No change required to add_related_holons function

Dance Enhancements

_In the dance_request.rs file:_

We need a way to convey the set of holons to be added. Each such holon could be staged or existing. The native reference types provided by the Holons zome (StagedReference and SmartReference) are overkill for this usage. So I propose the following:

[x] Introduce a new PortableReference type that provides a way to refer to existing or staged holons that is portable between client and guest:

pub enum PortableReference {
    Saved(HolonId),
    Staged(StagedIndex)
}

[x] Add a new TargetHolons variant in the RequestBody enum

pub enum RequestBody {
    None,
    Holon(Holon),
    TargetHolons(RelationshipName, Vec<PortableReference>) // <=== NEW
    ParameterValues(PropertyMap),
    Index(StagedIndex),
}

[x] Add to_holon_reference method on PortableReference that converts the PortableReference into a HolonReference with "None" used for all the "optional" fields.
[x] Add new_target_holons function to the impl of RequestBody

_In the holon_dance_adapter.rs file:_

[x] Add a new add_related_holons dance function that converts the PortableReferences into HolonReferences that can be passed to the existing native add_related_holons method on StagedReference

/// *DanceRequest:*
/// - dance_name: "add_related_holons"
/// - dance_type: Command(StagedIndex) -- references the staged holon that is the `source` of the relationship being extended
/// - request_body:
///     _TargetHolons_: whose associated data specifies the RelationshipName and the vector of PortableReferences to the holons being added
///
/// *ResponseBody:*
/// - _StagedIndex_ -- index into staged_holons for the updated source holon
///

[x] Add a new build_add_related_holons_dance_request function

In the dancer.rs file:

[x] Add "add_related_holons" dance to the Dancer's dispatch table

Testing Enhancements

[x] Add "test_add_related_holons" test step executor
[x] Add AddRelatedHolons as a variant in the DanceTestStep enum definition
[x] add its fmt::Display implementation
[x] Implement an `add_related_holons" function

_In the dance_fixture.rs file:_

[ ] Define a new simple_add_related_holons_fixture function consisting of the following steps:
- [x] Ensure database is empty
- [x] Stage New Holon -- for a book holon
- [x] Stage New Holon -- for a Person holon
- [x] Stage New Holon -- for an additional Person
- [x] Add "AUTHORED_BY" relationship from book to both persons
- [x] commit
- [ ] match database content -- get the book Holon and ensure it matches expected, get its AUTHORED_BY relationship. and ensure it returns the expected Persons, ensure each Person 's properties match expected. Resolved in Issue #76.

_In the dance_tests.rs file:_

[ ] Add a match that executes the AbandonStagedChanges step (deferred this to Issue #79 )

Definition of Done:

[x] After adding add_related_holons_test_steps to the simple_undescribed_create_holon_test, test case passes

evomimic / map-holons