Proposal: Evolution of MAP Interface Boundaries and TypeScript Client API

[evomimic]

Proposal: Evolution of MAP Interface Boundaries and TypeScript Client API

Audience: MAP Core Development Team
Status: Proposal for discussion and alignment
Motivation: Clarify and formalize the evolution of MAP interface boundaries in light of architectural realities that have emerged during implementation.

---

1. Background and Context

The MAP interface design originally treated the Dance interface as the primary external integration boundary. This made sense when:

• The guest was imagined as a backend service.
• Multiple external clients in different languages were anticipated.
• HTTP/REST interoperability was a design goal.
• Mapping internal errors to HTTP status codes seemed beneficial.

As implementation has progressed, several architectural facts have become clear that invalidate these assumptions and call for a refinement of the interface model.

---

2. Key Architectural Realizations

2.1 The Guest Is Not a Service Boundary

• The Holochain guest runs in a WASM sandbox.
• It cannot access external services.
• All external interactions are mediated by receptors in the Rust client.
• Guest ↔ client communication is Rust ↔ Rust, with shared types and shared error semantics.

Implication:
The guest is an execution environment, not an integration boundary.

---

2.2 The Rust Client Is the True Integration Point

• The Rust client:
  • Owns holon state (nursery, transient holon manager, cache).
  • Mediates all access to external services.
  • Hosts receptors (e.g. REST, filesystem, network protocols).
• Protocol translation (HTTP, REST, etc.) belongs at the receptor level, not in MAP core.

Implication:
Any mapping from internal semantics (e.g. errors) to protocol-specific representations must happen in receptors, not in the core API.

---

2.3 The TypeScript Client Is Privileged

• Runs in the same Tauri container and OS process as the Rust client.
• Does not traverse trust channels.
• Does not require authentication or signature verification.
• Never ping-pongs session or holon state.
• Operates exclusively on holon references and base values.

Implication:
The TypeScript client should not be constrained by assumptions appropriate only to remote or untrusted callers.

---

3. Consequences for Error and Status Handling

3.1 HTTP Status Codes Are No Longer Appropriate in Core APIs

• MAP already has a rich HolonError type:
  • Shared by guest and client.
  • Supports multiple errors and warnings.
  • Preserves detailed semantics.
• Mapping HolonError → HTTP status code:
  • Flattens information.
  • Introduces unnecessary coupling.
  • Is unnatural for Rust ↔ Rust communication.

Proposal:

• Remove status code fields from DanceResponse.
• Return serialized HolonError values directly.
• Perform protocol-specific mappings (e.g. to HTTP status codes) only:
  • In receptors, or
  • In TypeScript-side integrations if required by visualizers.

---

4. Rethinking the Role of the Dance Interface

4.1 Dance Is Not the Canonical MAP API

The Dance interface is well-suited for:

• Extensible workflows.
• User-defined or dynamically loaded behaviors.
• Promise-oriented interactions.

It is not well-suited for:

• Primitive holon accessors.
• Property reads/writes.
• Relationship traversal.
• Core state management operations.

Forcing all MAP interactions through DanceRequest / DanceResponse creates unnecessary complexity and leads to awkward indirection.

---

4.2 MAP Core APIs Already Exist Conceptually

MAP already defines a clear core surface:

• ReadableHolon
• WritableHolon
• HolonCollection
• HolonOperations API (staging, querying, committing, etc.)

These APIs:

• Operate on references.
• Preserve centralized state ownership in the Rust client.
• Avoid holon materialization outside Rust.

---

5. Proposal: Command-Oriented Client Interface

5.1 Commands as the Transport Unit (TypeScript-Only Interface)

Instead of treating Dance as the universal interface, expose MAP core functionality via commands — but only to the privileged TypeScript client.

The Command interface is not a general MAP integration surface. It is a local, privileged transport mechanism used exclusively for communication between the TypeScript client and the Rust client within the same Tauri process.

Key clarifications:

• Commands are not exposed across trust channels.
• Commands are not available to remote agents or external callers.
• Commands bypass authentication, signature verification, and agreement checks that apply to inter-agent interactions.
• Commands assume a shared process, shared lifecycle, and trusted execution context.

Within this constrained context:

• Each command represents a discrete MAP core operation.
• Commands are dispatched to local receptors inside the Rust client.
• Commands can be typed, audited, versioned, and undone/redone.
• Commands provide a clean transport for invoking:
  • holon accessors,
  • state mutations,
  • staging and commit operations.

Examples of TypeScript-only commands include:

• GetPropertyValue
• SetPropertyValue
• GetRelatedHolons
• StageHolon
• QueryHolons
• CommitNursery

This distinction ensures that:

• MAP Core APIs remain clean and protocol-agnostic.
• Security semantics remain intact at true agent boundaries.
• TypeScript bindings remain efficient and expressive without imposing constraints required for remote interoperability.

---

5.2 Dance as One Command Type

• Executing a Dance becomes one variant of a broader Command model.
• A DanceCommand:
  • Carries a DanceRequest.
  • Is routed either:
    • To a local client implementation, or
    • Through the Holochain receptor to the guest.
• This preserves extensibility without constraining core APIs.

---

5.3 Undo / Redo Alignment

• Writable operations are still commands.
• Command objects naturally support:
  • Undo/redo tracking.
  • Transactional grouping.
• Dance builders are not required for built-in MAP commands.

---

6. TypeScript API Implications

6.1 Direct Exposure of MAP Core Surface

The TypeScript client should interact with:

• ReadableHolon methods (e.g. property access).
• WritableHolon methods (mutations).
• HolonCollections (reference sets).
• HolonOperations API (creation, querying, staging).

All via:

• Typed commands dispatched locally.
• Reference-based results.
• Serialized base values and holon references.

---

6.2 Error Semantics

• TypeScript should be HolonError-literate.
• Errors are returned as structured data, not status codes.
• UI layers or visualizers may adapt errors to their own affordances if needed.

---

7. Summary of the Proposed Model

• MAP Core API
  • Exposed as typed commands.
  • No HTTP semantics.
  • Reference-based.
• Dance API
  • One extensible command among many.
• Receptors
  • The sole place for protocol translation and external service interaction.
• Trust Channels
  • Only involved when state crosses agent boundaries.
• TypeScript Client
  • Privileged, local, state-light, holon-aware.

---

8. Next Steps for the Core Team

Suggested follow-up discussions:

1. Define the canonical Command enum / hierarchy.
2. Specify undo/redo metadata requirements.
3. Formalize dance registration and routing rules.
4. Define the TypeScript binding surface for core commands.
5. Identify any remaining places where HTTP semantics still leak into core abstractions.

---

This proposal reflects the architecture MAP has already grown into.
The goal is to let the interfaces catch up with reality.

[owleyeview]

Thanks so much for writing this up @evomimic — this evolution feels super important and clarifying, and I really appreciate you laying it out so explicitly.

---

A few focused questions / clarifications as I digest this:

• status_code in DanceResponse
  You note that we'll be removing the status_code field from DanceResponse.
  Should the ResponseStatusCode enum itself also be removed from dance_response.rs and possibly relocated for use only in receptors (or other protocol-facing layers)?
  Related: should ResponseStatusCode.PropertyType be removed from the dance schema at this time as well?

• Dance plumbing vs core commands
  When the ClientHolonService needs to interact with the guest for persistence-related operations, will that still go through the existing dance plumbing internally? Will dances still be used at the host/guest boundary?

• State ownership rules
  I think it would be really helpful to work on making state ownership explicit as we move forward. Refining answers to question like:

  • Does the Rust client / integration hub always own the nursery / transient manager / session state?
  • When we say the guest is “stateless,” is that meant as “no durable ownership,” even though it operates over staged/transient pools passed in?
  • What, if anything, should be cached or retained in the TypeScript client?

• Naming and normalization
  I’m still a little fuzzy on naming, and it feels like a good moment to normalize:

  • Is there a meaningful distinction between Uniform API, MAP API, and MAP SDK right now, or are these all pointing at the same local command surface?
    If this is truly TS↔Rust only, maybe something like Local Command API would reduce ambiguity.
    Will there still be anything we’d call a Uniform Dance API?
  • I think it would help to land on a canonical name for the Rust side: Rust Client vs Integration Hub vs Host. Something like Host Integration Hub...?
  • You mention a “Local Receptor” that’s uniquely trusted, but also describe it as the Command Dispatcher. Since this is a special, privileged TS→Rust entrypoint, I like “Command Dispatcher” and moving away from the “local receptor” terminology here.

What do you all think?

---

Overall, this direction makes a ton of sense to me — these questions are mostly about tightening definitions so we’re all using the same mental model as we implement against it.

[evomimic]

Should the ResponseStatusCode enum itself also be removed from dance_response.rs and possibly relocated for use only in receptors (or other protocol-facing layers)?

A: yes!

When the ClientHolonService needs to interact with the guest for persistence-related operations, will that still go through the existing dance plumbing internally? Will dances still be used at the host/guest boundary?

A: yes!

State ownership rules
I think it would be really helpful to work on making state ownership explicit as we move forward. Refining answers to question like:

Does the Rust client / integration hub always own the nursery / transient manager / session state?

A: The Integration Hub always owns the nursery / transient manager / holons_cache state. When it initiates a DanceRequest to the guest, it passes this SessionState to the guest where it is inflated in the guest side into nursery / transient manager / holons_cache. This state is then ping-ponged back to the Integration Hub on return from the dance.

When we say the guest is “stateless,” is that meant as “no durable ownership,” even though it operates over staged/transient pools passed in?

A: Right. This can be a bit confusing. We say the guest is stateless because it retains no state from one request to the next. This is exactly why we MUST pass the state in.

What, if anything, should be cached or retained in the TypeScript client?

A: No holon state is cached or retained in the TypeScript client. Visualizers may hold property values.

[owleyeview]

I'm also wondering if this shift might affect how we think about where local file system access should take place.

During implementation of the loader client we had decided to isolate file system access to receptors, but how we're thinking about receptors seems to have changed and there may not be something that is considered a local receptor moving forward.