MAP Commands -- Phase 2.1 -- Define initial command set (v0)

[evomimic]

MAP Commands — Phase 2.1 — Establish Command Contract and Runtime Binding Seam (v0)

---

1. Summary (Required)

What is the enhancement?

Implement the initial MAP Commands contract defined in the
MAP Commands Specification.

This phase establishes the code scaffolding necessary to support the specification’s architecture:

• Canonical IPC envelope types (MapIpcRequest, MapIpcResponse)
• Structural command model (MapCommandWire)
• Post-bind domain command model (MapCommand)
• The Runtime binding seam (Wire → Domain)
• A minimal dispatcher path enabling end-to-end execution of at least one command

The goal of this phase is to make the command architecture compile, bind, and execute through the Runtime boundary, without yet implementing full lifecycle enforcement or full command coverage.

The MAP Commands Specification is the authoritative definition of the command architecture.
This issue focuses strictly on implementing that specification.

---

2. Problem Statement (Required)

Why is this needed?

Current command plumbing still reflects legacy assumptions:

• String-based command authority (name: String)
• Mixed or implicit command scope
• Binding and lifecycle policy distributed across ingress and receptor paths
• Inconsistent distinction between MAP domain commands and operational commands

Before centralizing execution inside Runtime, we must stabilize the command contract so the architecture becomes enforceable:

• IPC ingress accepts wire-layer types only
• Domain execution operates on domain command types only
• Command scope is explicit and structural
• Binding occurs exclusively inside Runtime::dispatch
• Lifecycle policy can be centralized in Runtime in Phase 2.2

This phase introduces the structural command model and binding seam required for that centralization.

---

3. Dependencies (Required)

Reference documentation:

• MAP Commands Specification
  https://memetic-activation-platform.github.io/map-dev-docs/core/commands

• MAP Commands Cheat Sheet
  https://memetic-activation-platform.github.io/map-dev-docs/core/commands-cheat-sheet/

These documents define the normative command model and command inventory.

Prerequisites already available:

• Transaction-bound reference model and lifecycle primitives in core
• Existing *Wire.bind(context) binding patterns
• Existing transaction context management

Must land before:

• Phase 2.2 Runtime dispatcher centralization
• Phase 3 single-domain-ingress cutover
• SDK contract stabilization for MAP commands

---

4. Implementation Tasks (Required)

4.1 Implement IPC Envelope Types

Define the canonical IPC request/response envelopes defined by the specification:

pub struct MapIpcRequest {
    pub request_id: RequestId,
    pub command: MapCommandWire,
}

pub struct MapIpcResponse {
    pub request_id: RequestId,
    pub result: Result<MapResultWire, HolonErrorWire>,
}

Rules:

• These types exist only at the IPC boundary
• They must be serializable
• They must not appear below the Runtime binding seam

---

4.2 Implement Structural Command Model

Implement the structural command hierarchy:

pub enum MapCommandWire {
    Space(SpaceCommandWire),
    Transaction(TransactionCommandWire),
    Holon(HolonCommandWire),
}

This replaces legacy string-based command routing.

Command authority must derive from the structural variant, not from strings.

---

4.3 Implement Domain Command Types

Define the post-binding domain command model:

pub enum MapCommand {
    Space(SpaceCommand),
    Transaction(TransactionCommand),
    Holon(HolonCommand),
}

Rules:

• Domain command types must not reference any *Wire types
• Domain types must not require serialization
• Transaction identifiers must be replaced by bound runtime objects (e.g., TransactionContextHandle)

---

4.4 Implement Runtime Binding Seam

Create the Runtime binding seam that converts wire commands into domain commands.

Binding must occur only inside Runtime.

Responsibilities include:

• Binding MapCommandWire → MapCommand
• Resolving transaction context
• Resolving holon references
• Returning deterministic errors for binding failures

---

4.5 Implement IPC Entrypoint

Implement the single IPC ingress defined by the specification:

#[tauri::command]
async fn dispatch_map_command(
    state: State<'_, Runtime>,
    request: MapIpcRequest,
) -> Result<MapIpcResponse, HolonErrorWire>

This function must:

• Accept wire-layer types only
• Delegate immediately to Runtime::dispatch
• Perform no binding
• Perform no lifecycle enforcement
• Perform no descriptor evaluation

---

4.6 Provide Minimal Dispatcher Implementation

Provide a minimal Runtime dispatcher capable of executing one command end-to-end.

Example structure:

Runtime::dispatch
  → bind
  → dispatch_command
  → dispatch_space / dispatch_transaction / dispatch_holon

All other commands may temporarily return NotImplemented.

The goal is to verify:

• wire/domain separation compiles
• binding seam functions correctly
• dispatcher path works end-to-end

Full dispatcher policy enforcement is deferred to Phase 2.2.

---

5. Scope and Impact (Required)

This issue impacts:

• MAP IPC command contract types
• TypeScript client command models
• Runtime command binding structure
• Command routing architecture

Not in scope for this phase:

• Full Runtime lifecycle policy enforcement
• Full command coverage
• Receptor removal or plumbing changes
• Descriptor enforcement implementation
• Tauri ingress cutover

Those are addressed in later phases.

---

6. Testing Considerations (Required)

Testing should verify the contract architecture works correctly:

• Serde roundtrip tests for IPC wire types
• Compile-time validation that domain types contain no *Wire references
• Basic integration test exercising the end-to-end dispatch path
• Validation of structural command routing

Legacy ingress paths may continue to function in parallel.

---

7. Definition of Done (Required)

This phase is complete when:

• MapIpcRequest and MapIpcResponse are implemented
• MapCommandWire structural command model is implemented
• Domain command model (MapCommand) compiles without wire dependencies
• Runtime binding seam (Wire → Domain) exists
• dispatch_map_command IPC entrypoint delegates to Runtime
• At least one command executes end-to-end through the new path
• Basic contract tests pass

---

This phase establishes the structural command contract and Runtime binding seam required for Phase 2.2 to centralize dispatcher policy and lifecycle enforcement inside Runtime.

[owleyeview]

Review Notes: Issue #404 — Inconsistencies and Open Questions

After reviewing the issue details alongside the MAP Commands Specification (v0.3.1), I've identified several inconsistencies and questions that need resolution before implementation begins. Documenting them here for discussion.

---

1. Type Naming Clarification: MapRequest/MapResponse vs. Wire Envelopes

Confirming my understanding of the type layering in the new Runtime ingress path:

• MapRequest and MapResponse will not exist in the new path.
• The correct runtime/domain types are MapCommand and MapResult.
• Their corresponding wire representations are MapCommandWire and MapResultWire.
• These are wrapped in the IPC envelope types MapRequestWire and MapResponseWire.

Is this correct?

---

2. Conflicting MapCommand Taxonomies (Spec vs. Suggested Rust Defs)

Issue #404 contains two structurally incompatible top-level MapCommand taxonomies:

• Scope-first — used in the phase description and the normative spec (Section 5):

  pub enum MapCommand {
      Space(SpaceCommand),
      Transaction(TransactionCommand),
      Holon(HolonCommand),
  }

• CQRS-first — used in the suggested (non-normative) Rust type definitions:

  pub enum MapCommand {
      ReadOnly(ReadOnlyCommand),
      Mutating(MutatingCommand),
  }
  // where each variant then contains scope branches

The CQRS split introduces meaningful problems:

• Every scope (Space, Transaction, Holon) appears twice — once under ReadOnly and once under Mutating — which doubles the variant surface with no structural benefit.
• CommandDescriptor.is_mutating already captures mutability metadata in the descriptor model, so the CQRS distinction is already expressible without restructuring the command enum.
• Adding this layer contradicts the spec, which has MapCommandWire branch directly to scope variants.

Recommendation: Follow the spec — scope-first at both the wire and domain levels. Express CQRS semantics via CommandDescriptor, not via a top-level enum split.

---

3. Redundant Error Types: HolonErrorWire, MapErrorWire, MapErrorCode

Two separate new error types are proposed across the spec and issue #404:

• HolonErrorWire (referenced in the spec as a wire-layer error type)
• MapErrorWire / MapErrorCode (introduced in the issue MAP Commands -- Phase 2.1 -- Define initial command set (v0) #404 Rust type suggestions)

The existing HolonError (in integrity_core_types) already derives Serialize and Deserialize and is used throughout the domain. It also includes InvalidWireFormat for binding failures, making it a reasonable fit as the wire-safe error surface.

Questions:

1. What is the justification for introducing a new wire error type rather than reusing HolonError?
2. If a wire error type is needed (e.g., to enforce that no domain-only variants leak across the boundary), which is normative — HolonErrorWire or MapErrorWire/MapErrorCode? These two proposals need to be reconciled.

---

4. Redundant ID Type: HolonIdWire

The suggested Rust types introduce HolonIdWire. The existing HolonId from core_types is already serializable. Unless there is a specific structural requirement that HolonId cannot satisfy at the wire layer (e.g., it carries behavior or non-serializable fields), introducing HolonIdWire adds unnecessary duplication. Please clarify the rationale, or remove it in favor of the existing type.

---

5. Normative Traits (SpaceAuthority, TransactionExecution, etc.)

The issue proposes execution traits such as SpaceAuthority and TransactionExecution with *Wire types in their signatures. The spec is explicit: domain types must not reference any *Wire types, and binding occurs exclusively inside Runtime::dispatch.

Traits that combine domain execution logic with wire-layer types in their signatures violate this invariant. Help me understand what these traits are intended to solve that Runtime::dispatch_command and its scope-specific delegates (dispatch_space, dispatch_transaction, dispatch_holon) do not already cover. If they are purely internal to the Runtime binding seam, that needs to be clearly scoped.

---

6. Proposed Phase Split (2.1 / 2.2)

If we keep this work as two issues, here is a proposed boundary that avoids scope creep in either:

Phase 2.1 should deliver:

• Finalized wire/domain contract types (MapRequestWire, MapResponseWire, MapCommandWire, MapCommand, scoped variants)
• The dispatch_map_command Tauri entrypoint
• The Runtime bind seam (interface + skeleton)
• A minimal runnable dispatcher: one fully wired command end-to-end; all others may return NotImplemented

Phase 2.2 should deliver:

• Full policy centralization (CommandDescriptor enforcement, lifecycle guards)
• Full command coverage across all scope branches
• Receptor path de-primary and deletion steps
• Parity testing and integration test coverage

---

7. Suggested Module Structure

Based on spec Section 2.4 ("MAP Commands are a host-side construct") and the constraint that holons_boundary is a shared/WASM-safe crate, here is a proposed layout:

New IPC contract types — host workspace only:

host/crates/holons_client/src/map_commands/
  or
host/crates/map_commands/

New MapCommandWire and related wire types must not go into holons_boundary, which is WASM-safe and shared with the guest layer.

Runtime domain types, binding, and dispatch — in Conductora:

host/conductora/src/runtime/mod.rs
host/conductora/src/runtime/runtime.rs
host/conductora/src/runtime/bind.rs
host/conductora/src/runtime/descriptor.rs
host/conductora/src/runtime/dispatch/space.rs
host/conductora/src/runtime/dispatch/transaction.rs
host/conductora/src/runtime/dispatch/holon.rs

Tauri transport layer — thin, delegates immediately:

host/conductora/src/map_commands/dispatch_map_command.rs

The existing map_request.rs can temporarily delegate to the new entrypoint and be removed in Phase 3.

---

[evomimic]

Responses to your comments from March 6th

Thanks for your questions. One thing they highlighted is the inconsistencies between the spec and the issue. These were most apparent in the Rust Type Definitions comment that was added before the spec and issue body were finalized. I failed to update the comment to match the revised issue and spec. The type definitions were non-normative (intended as examples only, not prescriptions to be followed). But because they diverged from the finalized design, they created confusion.

To reduce the risk of future inconsistencies, I removed the Rust Type Definitions comment and will treat the MAP Commands Specification as the authoritative definition of the command model.

Given that the spec is the source of truth, the role of the issue has been narrowed to:

• implement the structures defined in the spec
• establish the initial code scaffolding for the command contract
• verify the wire/domain separation compiles and binds correctly
• prepare the codebase for the dispatcher and lifecycle centralization in Phase 2.2

If any remaining discrepancies appear between issue discussion and the specification, the specification should be treated as the source of truth.

---

1. Type Naming Clarification: MapRequest/MapResponse vs. Wire Envelopes

Your question about the relationship between MapRequest, MapResponse, and MapCommand highlighted that the existing naming was conflating two different concepts:

• the IPC envelope crossing the Tauri boundary
• the command payload executed by the Runtime

To make the transport boundary explicit, the spec has been updated to adopt IPC-specific envelope terminology:

Adopted:

• MapIpcRequest
• MapIpcResponse
• MapCommandWire
• MapResultWire
• MapCommand
• MapResult

This makes the layering clearer:

MapIpcRequest
  → MapCommandWire
  → MapCommand

and on the response path:

MapResult
  → MapResultWire
  → MapIpcResponse

Types removed from the architecture

As part of this clarification, the following types were explicitly removed from the spec:

• MapRequest
• MapResponse
• MapRequestWire
• MapResponseWire

The architecture no longer uses a runtime MapRequest wrapper.
Runtime execution begins directly with the domain command type:

Runtime::dispatch(MapRequestWire)

2. Conflicting MapCommand Taxonomies (Spec vs. Suggested Rust Defs)

Yep. Sorry about that confusion. I've deleted the Rust Type Definitions to avoid the inconsistencies.

3. Redundant Error Types: HolonErrorWire, MapErrorWire, MapErrorCode

The existing HolonError (in integrity_core_types) already derives Serialize and Deserialize and is used throughout the domain. It also includes InvalidWireFormat for binding failures, making it a reasonable fit as the wire-safe error surface.

Agreed. I didn't intend to introduce new error types. I thought I'd removed those everywhere, but missed that the Rust Type Definitions smuggled them back in.

---

4. Redundant ID Type: HolonIdWire

The suggested Rust types introduce HolonIdWire. The existing HolonId from core_types is already serializable.

Agreed. No need for separate HolonIdWire type.

---

5. Normative Traits (SpaceAuthority, TransactionExecution, etc.)

The only place where *Wire types appeared in execution-layer traits was the non-normative Rust type definitions comment that had been added to the Issue as an implementation sketch.

That comment predated some of the design clarifications and was not kept in sync with the spec, which is why it appeared to contradict the architecture.

Now that the comment has been removed, I believe the inconsistency you noted is gone.

---

6. Proposed Phase Split (2.1 / 2.2)

I agree the original phase split (which deferred introducing the dispatch function until Phase 2.2 would have left us without the ability to test Phase 2.1 So introducing a minimal dispatch implementation in Phase 2.1 makes total sense.

Tweaked slightly to reflect the terminology changes:

Phase 2.1 should deliver:

• Finalized command contract types as defined in the spec
  (MapIpcRequest, MapIpcResponse, MapCommandWire, MapResultWire, MapCommand, MapResult, including scoped variants)
• The dispatch_map_command Tauri entrypoint
• The Runtime binding seam (interface + skeleton implementation)
• A minimal runnable dispatcher: one command wired end-to-end through the full path; all others may return NotImplemented

Phase 2.2 should deliver:

• Full policy centralization inside Runtime (CommandDescriptor enforcement, lifecycle guards, etc.)
• Full command coverage across all scope branches
• Receptor path de-primary and deletion steps
• Parity testing and integration test coverage

---

7. Suggested Module Structure

Overall your proposed structure looks good and is consistent with the MAP Commands spec and the host/guest separation constraints.

• Keeping IPC contract types (e.g., MapIpcRequest, MapCommandWire) outside holons_boundary is the right call.
• I prefer elevating map_commands to its own crate rather than bundling it inside holons_client.
• Your runtime module structure in Conductora aligns well with the scope-first command taxonomy. I'd add a dispatch/mod.rs as well.

So the final structure becomes:

runtime/
  mod.rs
  runtime.rs
  bind.rs
  descriptor.rs
  dispatch/
    mod.rs
    space.rs
    transaction.rs
    holon.rs

[owleyeview]

@evomimic

While implementing the HolonCommand surface, I wanted to confirm the intended API boundaries for ReadableHolon.

1. Should I assume that all ReadableHolon methods are intended to map to MAP commands, or is ReadableHolon broader than the eventual command surface?

2. Does is_accessible belong in ReadableHolon if that trait is meant to define the public API? It reads more like an internal guard/policy check than a user-facing read operation.

3. Should all_related_holons be part of the command surface? Its return type is RelationshipMap, whose doc comment says it should not be serialized and is for in-memory caching only.

4. Should clone_holon remain on ReadableHolon? It creates new transaction-scoped state rather than performing a pure read, so I'm wondering if it belongs on TransactionContext::mutation() instead.

Overall, I'm trying to determine whether the command model should mirror the current trait surface exactly, or treat the MAP command surface as a narrower public subset.

Here is my current ReadableHolonAction enum for reference:

pub enum ReadableHolonAction {
    /// `ReadableHolon::clone_holon()` → `TransientReference`
    CloneHolon,

    /// `ReadableHolon::essential_content()` → `EssentialHolonContent`
    EssentialContent,

    /// `ReadableHolon::summarize()` → `String`
    Summarize,

    /// `ReadableHolon::holon_id()` → `HolonId`
    HolonId,

    /// `ReadableHolon::predecessor()` → `Option<HolonReference>`
    Predecessor,

    /// `ReadableHolon::key()` → `Option<MapString>`
    Key,

    /// `ReadableHolon::versioned_key()` → `MapString`
    VersionedKey,

    /// `ReadableHolon::all_related_holons()` → `RelationshipMap`
    AllRelatedHolons,

    /// `ReadableHolon::into_model()` → `HolonNodeModel`
    IntoModel,

    /// `ReadableHolon::property_value(name)` → `Option<PropertyValue>`
    PropertyValue { name: PropertyName },

    /// `ReadableHolon::related_holons(name)` → `HolonCollection`
    RelatedHolons { name: RelationshipName },
}

[owleyeview]

Also noticed that into_model() and the underlying HolonNodeModel seem to be for guest-only internal code and that summarize() says its for logging purposes only. I'm assuming those don't belong on the public API surface.

[evomimic]

Agreed. We don't need commands for IntoModel, IsAccessible, or AllRelatedHolons. The first two should probably be moved out of ReadableHolon and into a HolonReferenceSupport trait. But we can defer that to a later PR.

Keep a Command for CloneHolon. It's defined on ReadableHolon because it doesn't mutate self (and it's legit to call on SmartReferences when no WritableHolon trait methods are). But is_mutating should be true for the CloneHolon CommandDescriptor.

BTW... usage of is_accessible should be dropped from build_target_staged in loader_holon_mapper:

The call on get_raw_property_map immediately following does its own is_accesible check.

  loader_transient.is_accessible(AccessType::Read)?;
  // Read the LoaderHolon's current property map (owned snapshot)
  let properties: PropertyMap = loader_transient.get_raw_property_map(context)?;