Refactor HolonReference Traits

[evomimic]

1. Summary (Required)

1. Introduce HolonWritable trait that defines the API that StagedReferences offer edit their underlying Holon (without exposing the Holon itself). Implementations for the trait functions already existing in StagedReference. They just need to be moved into a trait implementation block.
2. Rename HolonGettable trait to HolonReadable and extend it to include essential_content and is_accessible methods.

2. Problem Statement (Required)

• Make it clearer which of the methods offered by StagedReference actually mutate a Holon's state and which don't.
• Use consistent trait naming conventions

3. Dependencies (Required)

None

4. Proposed Solution (Required)

• Define a HolonWritable trait in a new holon_writable.rs file within the holons src module
• It should include the following functions:

fn abandon_staged_changes(&mut self, context: &HolonsContext)
    -> Result<(), HolonError>;

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

fn commit(&self, context: &HolonsContext) -> Result<Holon, HolonError>;

fn clone_reference(&self) -> StagedReference;

fn get_id(&self, context: &HolonsContext)-> Result<HolonId, HolonError>;

fn get_predecessor(&self, context: &HolonsContext,)
    -> Result<Option<HolonReference>, HolonError>;

fn remove_related_holons(&self, context: &HolonsContext,
    relationship_name: &RelationshipName, holons: Vec<HolonReference>,)
    -> Result<(), HolonError>;

fn stage_new_from_clone(&self, context: &HolonsContext)
    -> Result<Holon, HolonError>;

fn with_descriptor(&self, context: &HolonsContext,
    descriptor_reference: HolonReference,)
    -> Result<&Self, HolonError>;

fn with_predecessor(&self, context: &HolonsContext,
    predecessor_reference_option: Option<HolonReference>,)
    -> Result<(), HolonError>;

fn with_property_value(&self, context: &HolonsContext,
    property: PropertyName, value: BaseValue,)
    -> Result<&Self, HolonError>;

• Rename HolonGettable to HolonReadable
• Add the following trait methods to HolonReadable:

fn essential_content(&self, context: &HolonsContext,)
   -> Result<EssentialHolonContent, HolonError>;

fn is_accessible(&self, context: &HolonsContext,
 access_type: AccessType,) -> Result<(), HolonError>

• Adjust the implementations of HolonReference, SmartReference and StagedReference to reflect HolonReadable trait definition.
• Adjust the implementations of StagedReference to reflect HolonWritable trait definition
• Delete the get_relationship_map() method from StagedReference

---

5. Scope and Impact (Required)

Reference Layer and consumers of the Reference Layer.

6. Testing Considerations (Required)

As this doesn't introduce any functional changes, no new test cases are required.

7. Definition of Done (Required)

• All existing test cases pass

[evomimic]

This enhancement is completed and will be closed when branch 188 is merged.