Map Commands Architecture Direction

[owleyeview]

Architecture Direction: Runtime as the Sole MAP Command Ingress

This note documents the architectural direction I am currently implementing. The goal is to align the codebase with the architecture we already intend, simplify the command execution path, and prepare the system for upcoming undo/redo functionality.

This work also advances the goals of issues #405 and #406 (roadmap Phase 2.2 and Phase 3).

I'm sharing it so the team has visibility into the direction and an opportunity to raise concerns before the refactor lands.

---

Key Direction

The core change is to fully consolidate MAP command execution around Runtime.

The architecture will move toward:

one state tree, one transaction owner, one ingress pathway.

Specifically:

• Runtime becomes the only local command ingress path for MAP operations.
• Command dispatch becomes the authoritative lifecycle and validation boundary.
• The legacy receptor-based ingress path is removed.
• Dance remains a first-class command with runtime-detected mutation behavior.
• Request options support undo/redo snapshot grouping.
• Transaction-managed pools track monotonic revision counters to detect mutation across commands and dances.

---

Command Ingress

dispatch_map_command will become the single Tauri command for MAP operations.

The legacy map_request path will be removed from AppBuilder registration.

All MAP commands will flow through:

Tauri
  → dispatch_map_command
    → Runtime
      → RuntimeSession
        → TransactionContext
          → Command dispatch
            → MAP core or Dance

This consolidates execution policy, lifecycle validation, and mutation detection in one place.

---

Command Descriptors

Each MAP command will define a CommandDescriptor describing its execution requirements and mutation classification.

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

pub struct RequestOptions {
    pub gesture_id: GestureId,
    pub gesture_label: Option<String>,   // e.g. "Set title to 'Foo'"
    pub snapshot_after: bool,            // close the gesture and capture snapshot
}

pub struct CommandDescriptor {
    pub mutation: MutationClassification,
    pub requires_open_tx: bool,
    pub requires_commit_guard: bool,
}

pub enum MutationClassification {
    ReadOnly,
    Mutating,
    RuntimeDetected,
}

Descriptor semantics

Built-in commands will declare their mutation behavior statically.

Dance will use:

MutationClassification::RuntimeDetected

because dances are extensible and cannot be classified statically.

Example:

impl MapCommand {
    pub fn descriptor(&self) -> CommandDescriptor {
        match self {
            Self::BeginTransaction => CommandDescriptor {
                mutation: MutationClassification::Mutating,
                requires_open_tx: false,
                requires_commit_guard: false,
            },
            Self::Dance(_) => CommandDescriptor {
                mutation: MutationClassification::RuntimeDetected,
                requires_open_tx: true,
                requires_commit_guard: false,
            },
        }
    }
}

Descriptors will live alongside command definitions so execution policy stays close to the commands themselves.

---

Lifecycle Enforcement

Lifecycle validation currently implemented in HolochainReceptor will move into the command dispatch layer.

The dispatch layer will enforce:

• open transaction requirements
• commit guard requirements
• mutation classification
• runtime mutation detection for Dance

This makes the command layer the single source of truth for execution policy.

---

Receptor Changes

The current HolochainReceptor and ReceptorBehavior will be retired from the local MAP command ingress path.

Runtime already executes dances through a TrustChannel whose backend transport is HolochainConductorClient. Because of this, the old receptor layer is no longer needed as a parallel ingress mechanism.

The broader architectural idea of receptors still exists, but their role is narrower:

• outbound integration adapters
• protocol bridges
• trust-mediated communication boundaries

They are no longer used as privileged local command ingress.

---

Runtime Mutation Detection for Dance

Because dances are extensible, mutation classification must be detected at runtime.

To support this, transaction-managed holon pools will gain monotonic version counters.

The dispatcher will:

1. record pool versions before command execution
2. execute the command or dance
3. compare versions after execution

If versions changed, the dispatcher knows the operation mutated transaction-managed state.

This works naturally with the dance round-trip behavior.

During a dance:

• the guest returns updated staged and transient pools
• the host reimports them via import_staged_holons() and import_transient_holons()

If those import methods only bump version counters when the pool actually changes, then mutation detection becomes automatic:

• read-only dances return identical state → no version change
• mutating dances return modified state → version increments

This allows mutation detection without special-case dance logic.

Important detail

Pool imports must bump version counters only when the imported state differs.

If a read-only dance returns the same pool contents it received, the import should be a no-op. Otherwise we would produce false mutation signals.

The version counters provide the correct abstraction level for:

• snapshot gating
• undo/redo checkpoints
• future journaling layers

---

Gesture-Based Snapshot Control

Undo/redo checkpointing will be controlled by request options, not by command descriptors.

RequestOptions includes:

• gesture_id
• gesture_label
• snapshot_after

This supports cases where a single user interaction triggers multiple commands and only the final command should close the gesture and capture a snapshot.

gesture_id provides a stable grouping identifier so two sequential gestures with the same label are still distinct.

---

Runtime Setup Flow

The intended Tauri setup flow becomes:

1. Register only dispatch_map_command for MAP operations.

2. Holochain plugin fires setup-completed.

3. run_complete_setup performs:

   apply setups

   HolochainSetup::setup()
   → create HolochainConductorClient
   → store in state
   

   initialize runtime

   TrustChannel(HolochainConductorClient)
      ↓
   init_client_runtime(Some(trust_channel))
      ↓
   HolonSpaceManager
      ↓
   RuntimeSession::new(space_manager)
      ↓
   Runtime::new(session)
      ↓
   Runtime stored in RuntimeState
   

RuntimeSession becomes the owner of all transaction lifecycle.

Runtime becomes the only ingress surface.

---

Cleanup Work

This direction implies the following cleanup work:

• remove map_request from AppBuilder
• retire the current HolochainReceptor from the command path
• move lifecycle validation into command dispatch
• add pool version counters
• add gesture_id to request options

---

Naming Consideration

Once the current HolochainReceptor is removed, it may make sense to rename HolochainConductorClient to HolochainReceptor.

This would align naming with the architecture diagram and reflect the newer meaning of receptors as trust-mediated outbound adapters.

This rename is optional and not required for the refactor.

---

Open Questions

A few details still need decisions:

GetAllSpaces command

We may want a GetAllSpaces MAP command depending on how multi-space management evolves.

CommandDescriptor location

The current direction is to colocate descriptors with command variants, but this can still be adjusted if needed.

Remove LocalReceptor and ReceptorFactory

I suggest removing the current implementations of:

• LocalReceptor
• ReceptorFactory

or at minimum marking them as legacy compatibility code pending removal.

If we no longer support receptor-based local ingress, these abstractions are no longer central to the architecture.

Summary

The intended architecture becomes:

• Runtime is the only MAP command ingress
• command dispatch owns lifecycle enforcement
• Dance remains extensible with runtime mutation detection
• undo/redo grouping is request-driven
• receptors remain only as outbound integration adapters

This completes the transition toward a cleaner MAP execution model built around commands, transactions, and runtime dispatch.