Pure Holonic Dance API

[evomimic]

2. Problem Statement

Over time, the MAP Dance API has evolved organically across multiple layers of the stack. While it has proven workable, it is not yet holonic — meaning that the key data structures that represent a dance, its request, and its response are not themselves Holons described within the MAP Type System.

The current MAP Dance API is a procedural artifact that predates the new MAP Dance Schema-v0.0.2, which now fully defines how dances, requests, responses, and implementations relate as holons. The schema expresses the ontology of dances as a unified, self-describing model, but the runtime still implements an older, code-driven envelope pattern that duplicates this logic manually.

---

A. Fragmented API Surface

At present, the Rust client defines separate structs for DanceRequest and DanceResponse, with enums for payloads and status codes:

pub struct DanceRequest {
    pub dance_name: MapString,
    pub dance_type: DanceType,
    pub body: RequestBody,
    pub state: Option<SessionState>,
}

pub struct DanceResponse {
    pub status_code: ResponseStatusCode,
    pub description: MapString,
    pub body: ResponseBody,
    pub descriptor: Option<HolonReference>,
    pub state: Option<SessionState>,
}

These procedural structs function as envelopes for data exchange but are not themselves Holons.
Their shape and meaning are defined by Rust code rather than by the MAP Type System, making them opaque to schema-level discovery, validation, and introspection.

---

B. Ad-hoc Payload Enums

The request and response bodies rely on fixed enums that must be edited and recompiled whenever new payload types are introduced:

pub enum RequestBody {
    None,
    Holon(Holon),
    TargetHolons(RelationshipName, Vec<HolonReference>),
    TransientReference(TransientReference),
    HolonId(HolonId),
    ParameterValues(PropertyMap),
    StagedRef(StagedReference),
    QueryExpression(QueryExpression),
}

pub enum ResponseBody {
    None,
    Holon(Holon),
    HolonCollection(HolonCollection),
    Holons(Vec<Holon>),
    HolonReference(HolonReference),
    NodeCollection(NodeCollection),
}

This pattern creates a closed world: the host must know every possible body variant at compile time.
It also breaks alignment with the type system—payloads cannot be validated as instances of HolonTypes, nor can they be extended declaratively by spaces or downstream schemas.

---

C. Contextual Leakage

The same DanceRequest type is used across three distinct runtime contexts—TypeScript client, Rust client, and Holochain guest—even though their state models differ:

Context	State Model	Result
TypeScript Client	Holds only transient view-state; never persists model data.	state: Option<SessionState> field remains unused.
Rust Client	Maintains Transient, Staged, and Saved holons in memory.	Same struct must represent both local and remote dances.
Rust Guest	Stateless lambda-style executor.	Must serialize and ping-pong entire state bundles to simulate persistence.

For example, the same conceptual “CreateEmptyTransient” dance takes different forms depending on where it runs:

// Client-side invocation
DanceRequest {
    dance_name: "HolonOps.CreateEmptyTransient",
    dance_type: DanceType::Standalone,
    body: RequestBody::None,
    state: None,
}

// Guest-side invocation
DanceRequest {
    dance_name: "HolonOps.CreateEmptyTransient",
    dance_type: DanceType::CommandMethod(some_ref),
    body: RequestBody::TransientReference(some_ref),
    state: Some(SessionState::from_guest()),
}

Thus, the same logical action is represented by two structurally different envelopes, tied to runtime context rather than schema.

---

D. Missing Self-Description and Composability

Because DanceRequest and DanceResponse are not Holons:

• They lack a DescribedBy link to a DanceType or DanceResponseType.
• They cannot participate in the MAP introspection query model (“What are you?” → DescribedBy).
• They cannot be wrapped in higher-order envelopes such as TrustChannel, CapabilityEnvelope, or AuditEnvelope.
• The mappings between dances, their request types, and their response types exist only in Rust match tables.

This prevents schema-driven validation, automated documentation, and dynamic composition of dances.

---

E. Divergence From the Declared Schema

The MAP Dance Schema-v0.0.2 already defines a complete holonic model for dances:

Procedural Concept	Holonic Equivalent (Schema)
dance_name string	DanceName.PropertyType
DanceType enum	DanceType holon
DanceResponse struct	DanceResponseType holon
ResponseStatusCode enum	ResponseStatusCode.EnumValue + variants
Hard-coded dispatch tables	(HolonType)-[Affords]->(DanceType) and (TypeDescriptor)-[ImplementsDance]->(DanceImplementation)
Ad-hoc module metadata	Properties on DanceImplementation (Engine, ModuleRef, Entrypoint, etc.)

However, none of these holonic descriptors are used by the runtime.
Instead, the Rust API reconstructs them procedurally, duplicating their structure and logic in code.
This schema–runtime divergence means:

• Dances cannot be introspected or extended via the MAP Type System.
• The dispatcher cannot resolve implementations via the Affords and ImplementsDance relationships.
• TrustChannel envelopes cannot treat a Dance as a first-class holon.

---

F. Summary of the Problem

The current MAP Dance API:

1. Uses procedural structs instead of holonic, self-describing data.
2. Couples request and response shapes to runtime context.
3. Hard-codes payload variants and status codes instead of deferring to the schema.
4. Ignores existing DanceType, DanceResponseType, and DanceImplementation descriptors.
5. Prevents schema-driven discovery, validation, and composition of dances.

Until the runtime refactors to treat Dance, DanceRequest, and DanceResponse as first-class Holons described by the MAP Dance Schema,
the system will continue to suffer from schema–runtime divergence, limited extensibility, and redundant implementation logic.