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

[evomimic]

MAP Commands — Phase 2.1 — Define Initial Command Contract and Sandwich Boundaries (v0)

---

1. Summary (Required)

What is the enhancement?
Define and implement the initial MAP Commands contract (v0) as a strongly-typed IPC model with explicit wire/domain separation ("sandwich model") between:

• TypeScript SDK
• Conductora Tauri host ingress
• IntegrationHub Runtime domain dispatch

This phase establishes:

• Canonical wire envelopes (MapRequestWire, MapResponseWire)
• Structural scoped command model (MapCommandWire and scoped variants)
• Post-bind domain command model (MapCommand, scoped domain variants)
• Explicit binding seam: Wire -> Domain inside Runtime::dispatch
• Clear separation of MAP domain ingress vs operational control-plane commands

The goal is:

Every TS-visible MAP domain operation maps to a single MapCommandWire variant, which binds to a single domain command shape and a stable Runtime dispatch target.

---

2. Problem Statement (Required)

Why is this needed?
Current command plumbing still reflects legacy assumptions:

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

Before dispatcher/cutover work, we must stabilize the contract so architecture is enforceable:

• Domain ingress accepts wire types only
• Domain execution uses domain types only
• Scope is structural and explicit
• Lifecycle/policy decisions can be centralized in Runtime in Phase 2.2
• Operational endpoints (is_service_ready, etc.) remain explicitly out-of-band

---

3. Dependencies (Required)

Reference docs: MAP Commands Spec and MAP Commands Cheat Sheet define baseline vocabulary and command inventory for v0 alignment.

Does this depend on other issues or features?

• Transaction-bound reference model and lifecycle primitives already available in core
• Existing wire binding primitives (*Wire.bind(context)) available for reuse
• No requirement to remove legacy ingress in this phase

Must land before:

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

---

4. Proposed Solution (Required)

How would you solve it?

4.1 Define Canonical Wire Envelopes

Introduce/standardize:

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

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

Rules:

• Wire types are transport-only and serializable
• Wire types carry identifiers and payload data, not runtime behavior
• Wire types must not appear below Runtime binding seam

---

4.2 Define Structural Command Scope at Wire Layer

Define MapCommandWire with explicit scope branches:

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

Define scoped payload enums/structs (v0 set) with no name: String authority.

Remove from target contract:

• string command routing as authority
• generic mixed-scope request body as authority
• implicit scope inference

---

4.3 Define Post-Bind Domain Command Surface

Define domain command shapes with no wire dependencies:

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

Transaction/Holon domain variants should carry bound runtime objects (e.g., TransactionContextHandle, HolonReference) rather than wire payloads or loose identifiers.

Rules:

• No *Wire types in domain command structs/enums
• No serialization requirements in domain command types
• No separate tx_id string fields once binding has completed

---

4.4 Define Binding Responsibilities (Contract Only)

This phase does not implement full dispatcher behavior (Phase 2.2), but defines normative responsibilities:

• Wire -> Domain binding occurs only in Runtime::dispatch
• Holon-scoped binding resolves tx provenance from reference where required
• Transaction-scoped binding resolves tx_id -> context handle
• Binding failures map to deterministic wire-safe errors

---

4.5 Define Domain vs Ops Interface Boundary

Codify two command planes:

1. MAP Domain Plane

   • Uses MapRequestWire/MapCommandWire
   • Will flow through dispatch_map_command -> Runtime::dispatch (Phase 2.3)

2. Operational Control Plane

   • Readiness/health/diagnostics (e.g., is_service_ready)
   • Out of MAP command model scope
   • Must not bypass Runtime if invoking domain execution

This ensures later addition/retention of status commands does not violate the single domain ingress invariant.

---

4.6 Initial v0 Command Set (Contract Scope)

Define and freeze v0 contract coverage (exact naming may follow existing domain naming conventions):

• Space:
  • BeginTransaction
• Transaction:
  • Lifecycle: Commit (and optional Rollback placeholder if retained)
  • Mutation: create/stage/update/relationship/load/delete variants
  • Lookup: collection/read/count/space-anchor variants
  • Dance invocation variants
  • Graph query placeholder (optional, returns NotImplemented if included)
• Holon:
  • Read and write action families over bound HolonReference

---

5. Scope and Impact (Required)

What does this impact?

• MAP command contract types in host + TS boundary models
• Scoped command taxonomy and payload modeling
• Elimination plan for string-based command authority
• Prerequisite contract for Runtime centralization in Phase 2.2

Not in scope for this phase:

• Full runtime dispatch implementation
• Tauri cutover/removal of legacy ingress
• Receptor plumbing changes
• Descriptor enforcement implementation details (contract only in this phase)

---

6. Testing Considerations (Required)

How will this enhancement be tested?

• Wire model serde roundtrip tests for each command variant
• Domain model compile-time separation checks (no *Wire leakage)
• Mapping tests from TS request builders to structural wire variants
• Contract validation tests for required/invalid scoped payload shapes

Legacy tests should continue to run; this phase is contract-first and can coexist with legacy ingress paths.

---

7. Definition of Done (Required)

When is this enhancement complete?

• Canonical MapRequestWire and MapResponseWire are defined and used for v0 contract surface
• MapCommandWire structural scope model is defined (Space/Transaction/Holon)
• Post-bind domain command model is defined with no wire dependencies
• String-based command authority is removed from the target contract model
• Binding seam responsibilities are documented as Runtime-owned
• Domain-vs-ops interface boundary is explicit in docs/types
• v0 command set is frozen at contract level
• Contract serde/shape tests pass

---

This phase stabilizes the MAP command contract so Phase 2.2 can implement centralized Runtime dispatch policy without ambiguity, and Phase 2.3 can cut over to a single domain ingress safely.

[evomimic]

Rust Type Definitions

These are suggested definitions (not normative).

//! MAP Commands v0 — Rust type defs aligned to:
//! - CQRS: ReadOnly vs Mutating (top-level)
//! - Scope-aware commands: Space / Transaction / Holon / Dance / GraphQuery
//! - "Sandwich model": wire types live at IPC boundaries; runtime types bind internally.
//!
//! Notes:
//! - SpaceAuthority is a hub-runtime object. It is NOT IPC-serializable.
//! - TransactionContext is NOT IPC-serializable; tx_id binds to Arc<TransactionContext>.
//! - HolonReferenceWire carries tx provenance; holon-scoped commands do NOT take tx_id separately.
//! - Dances are invoked as commands but remain the MAP extensibility surface (domain layer).
//! - GraphQuery is reserved placeholder in v0.

use serde::{Deserialize, Serialize};

// -----------------------------------------------------------------------------
// Common wire primitives (placeholders; use your existing types)
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct RequestId(pub String);

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct SpaceId(pub String);

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct TxId(pub u64);

// If you already have MapString etc., replace these aliases.
pub type MapString = String;

// You already have these in core_types; re-use directly in real code.
pub type PropertyMap = std::collections::BTreeMap<String, serde_json::Value>;
pub type RelationshipName = String;
pub type PropertyName = String;

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub struct LocalId(pub Vec<u8>);

// These are your existing wire references/holons; keep them in holons_boundary.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum HolonReferenceWire {
    Transient(TransientReferenceWire),
    Staged(StagedReferenceWire),
    Smart(SmartReferenceWire),
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TransientReferenceWire {
    pub tx_id: TxId,
    pub temporary_id: u32,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct StagedReferenceWire {
    pub tx_id: TxId,
    pub temporary_id: u32,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SmartReferenceWire {
    pub tx_id: TxId,
    pub holon_id: HolonIdWire,
    pub cached_properties: Option<PropertyMap>, // best-effort projection cache (optional)
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
pub enum HolonIdWire {
    Local(LocalId),
    External { proxy_id: LocalId, local_id: LocalId },
}

// For payloads/results, you can keep using your existing HolonWire/HolonCollectionWire/etc.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum HolonWire {
    // placeholder
    Saved { id: HolonIdWire, properties: PropertyMap },
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HolonCollectionWire(pub Vec<HolonWire>);

// -----------------------------------------------------------------------------
// MapRequest / MapResponse (Wire)
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct MapRequestWire {
    pub request_id: RequestId,
    pub command: MapCommandWire,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct MapResponseWire {
    pub request_id: RequestId,
    pub result: Result<MapResultWire, MapErrorWire>,
}

// You can keep this small and evolve it; include enough to round-trip results deterministically.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum MapResultWire {
    None,

    // ---- Space-scoped results
    TxOpened(TxOpenedWire),

    // ---- Transaction lifecycle results
    Commit(CommitResultWire),
    Rollback(RollbackResultWire),

    // ---- Transaction mutation results
    TransientRef(TransientReferenceWire),
    StagedRef(StagedReferenceWire),
    LoadHolons(LoadHolonsResultWire),

    // ---- Lookups / holon reads
    Holon(Option<HolonWire>),
    Holons(HolonCollectionWire),
    HolonRefs(Vec<HolonReferenceWire>),
    Count(u64),

    // ---- Dance results (opaque-ish; domain defined)
    DanceResult(DanceResultWire),

    // ---- GraphQuery placeholder
    GraphQueryResult(GraphQueryResultWire),
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct MapErrorWire {
    pub code: MapErrorCode,
    pub message: String,
    pub details: Option<PropertyMap>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum MapErrorCode {
    NotImplemented,
    InvalidCommand,
    InvalidScope,
    TransactionNotOpen,
    TransactionCommitInProgress,
    TransactionAlreadyCommitted,
    CrossTransactionReference,
    HolonNotFound,
    PermissionDenied,
    InternalError,
}

// -----------------------------------------------------------------------------
// Top-level CQRS split
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum MapCommandWire {
    ReadOnly(ReadOnlyCommandWire),
    Mutating(MutatingCommandWire),
}

// -----------------------------------------------------------------------------
// ReadOnly command families (v0)
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ReadOnlyCommandWire {
    // Space-scoped read-only (optional in v0; keep placeholder)
    Space {
        space_id: SpaceId,
        command: SpaceReadOnlyCommandWire,
    },

    // Transaction-scoped lookup facade
    Transaction {
        tx_id: TxId,
        command: TransactionLookupCommandWire,
    },

    // Holon-scoped read (reference carries tx provenance)
    Holon {
        reference: HolonReferenceWire,
        command: HolonReadCommandWire,
    },

    // Read-only dance invocation (extensible surface)
    ReadOnlyDance {
        tx_id: TxId,
        dance_name: MapString,
        body: PropertyMap,
        options: Option<DanceInvokeOptionsWire>,
    },

    // Reserved placeholder (v0 returns NotImplemented)
    GraphQuery {
        tx_id: TxId,
        command: GraphQueryCommandWire,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum SpaceReadOnlyCommandWire {
    // placeholder for later: DescribeSpace, GetSpaceStatus, etc.
    NotUsedV0,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum TransactionLookupCommandWire {
    GetAllHolons,
    GetStagedByBaseKey { key: MapString },
    GetStagedByVersionedKey { key: MapString },
    GetTransientByBaseKey { key: MapString },
    GetTransientByVersionedKey { key: MapString },
    StagedCount,
    TransientCount,
    GetSpaceHolon, // returns Option<HolonReferenceWire> (wire)
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum HolonReadCommandWire {
    ReadHolon,
    GetRelatedHolons { relationship_name: RelationshipName },
    GetAllRelatedHolons, // optional
}

// Reserved placeholder; keep shape stable but unimplemented in v0.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum GraphQueryCommandWire {
    NavigationAlgebra { expr: String, params: PropertyMap },
    CypherExpression { cypher: String, params: PropertyMap },
}

// -----------------------------------------------------------------------------
// Mutating command families (v0)
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum MutatingCommandWire {
    // Space-scoped mutation (transaction authority)
    Space {
        space_id: SpaceId,
        command: SpaceMutatingCommandWire,
    },

    // Transaction lifecycle + mutation facade
    Transaction {
        tx_id: TxId,
        command: TransactionMutatingCommandWire,
    },

    // Holon-scoped mutation (v0 recommendation: omit and route via tx mutation only)
    Holon {
        reference: HolonReferenceWire,
        command: HolonMutatingCommandWire,
    },

    // Mutating dance invocation (extensible surface)
    MutatingDance {
        tx_id: TxId,
        dance_name: MapString,
        body: PropertyMap,
        options: Option<DanceInvokeOptionsWire>,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum SpaceMutatingCommandWire {
    BeginTransaction(BeginTransactionWire),
    // future: CloseSpace, EnsureSpaceLoaded, etc.
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct BeginTransactionWire {
    pub mode: BeginTransactionModeWire,
    pub tx_id_hint: Option<TxId>, // optional: preserve tx_id across IPC round-trips if needed
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum BeginTransactionModeWire {
    Default, // "ensure default exists" semantics (optional)
    New,     // always creates a new tx
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum TransactionMutatingCommandWire {
    // Lifecycle (still "mutating" because it mutates tx state)
    Commit,
    Rollback, // optional v0.1+; v0 may return NotImplemented

    // Mutation facade operations
    Mutation(TransactionMutationCommandWire),
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum TransactionMutationCommandWire {
    // Transient creation
    CreateTransientHolon { key: Option<MapString> },

    // Staging
    StageNewHolon { transient: HolonReferenceWire },
    StageNewFromClone { original: HolonReferenceWire, new_key: MapString },
    StageNewVersion { current: HolonReferenceWire },

    // Property mutation (choose normative target: holon-surface vs tx.mutation())
    SetProperty { target: HolonReferenceWire, property_name: PropertyName, value: serde_json::Value },
    UnsetProperty { target: HolonReferenceWire, property_name: PropertyName },

    // Relationship mutation
    AddRelationship {
        source: HolonReferenceWire,
        relationship_name: RelationshipName,
        target: HolonReferenceWire,
    },
    RemoveRelationship {
        source: HolonReferenceWire,
        relationship_name: RelationshipName,
        target: HolonReferenceWire,
    },

    // Delete (if supported v0 path)
    DeleteHolon { local_id: LocalId },

    // Import / ingress that creates/stages holons
    LoadHolons { bundle: HolonReferenceWire },
}

// v0 recommendation: do NOT expose separate holon-write commands;
// keep mutations centralized under TransactionMutationCommandWire.
// Keep this enum only if you explicitly decide to support holon-write as a separate scope.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum HolonMutatingCommandWire {
    // placeholder; prefer NotUsedV0 and route through tx mutation
    NotUsedV0,
}

// -----------------------------------------------------------------------------
// Results payload shapes (wire)
// -----------------------------------------------------------------------------
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct TxOpenedWire {
    pub tx_id: TxId,
    // optional: include any immediately useful snapshot values (space holon id, etc.)
    pub space_holon_id: Option<HolonIdWire>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct CommitResultWire {
    // Keep it minimal; or mirror your existing commit response.
    pub committed: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct RollbackResultWire {
    pub rolled_back: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct LoadHolonsResultWire {
    pub imported_count: u64,
    pub errors: Vec<MapErrorWire>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DanceInvokeOptionsWire {
    pub timeout_ms: Option<u64>,
    pub trace: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct DanceResultWire {
    // Domain-defined; keep as an extensible payload.
    pub payload: PropertyMap,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct GraphQueryResultWire {
    // Placeholder for future; v0 likely returns NotImplemented.
    pub rows: Vec<PropertyMap>,
}

// -----------------------------------------------------------------------------
// Normative dispatch targets — expressed as traits/signatures (not impls)
// These are NOT serialized; they define what host code must call.
// -----------------------------------------------------------------------------

/// Space-scoped runtime authority (hub-owned).
/// NOT exposed via IPC; space_id binds to this via a hub SpaceRegistry.
pub trait SpaceAuthority {
    fn begin_transaction(
        &self,
        space_id: &SpaceId,
        mode: BeginTransactionModeWire,
        tx_id_hint: Option<TxId>,
    ) -> Result<TxOpenedWire, MapErrorWire>;
}

/// Transaction-scoped execution surface (transaction-owned).
/// tx_id binds to Arc<TransactionContext> via a hub TransactionRegistry.
pub trait TransactionExecution {
    // lifecycle
    fn commit(&self) -> Result<CommitResultWire, MapErrorWire>;
    fn rollback(&self) -> Result<RollbackResultWire, MapErrorWire>;

    // facades
    fn mutation(&self) -> &dyn TransactionMutationExecution;
    fn lookup(&self) -> &dyn TransactionLookupExecution;
    fn dance(&self) -> &dyn TransactionDanceExecution;
}

/// Mutation facade execution targets (normative).
pub trait TransactionMutationExecution {
    fn create_transient_holon(&self, key: Option<MapString>) -> Result<TransientReferenceWire, MapErrorWire>;
    fn stage_new_holon(&self, transient: HolonReferenceWire) -> Result<StagedReferenceWire, MapErrorWire>;
    fn stage_new_from_clone(&self, original: HolonReferenceWire, new_key: MapString) -> Result<StagedReferenceWire, MapErrorWire>;
    fn stage_new_version(&self, current: HolonReferenceWire) -> Result<StagedReferenceWire, MapErrorWire>;

    fn set_property(&self, target: HolonReferenceWire, property_name: PropertyName, value: serde_json::Value) -> Result<(), MapErrorWire>;
    fn unset_property(&self, target: HolonReferenceWire, property_name: PropertyName) -> Result<(), MapErrorWire>;

    fn add_relationship(&self, source: HolonReferenceWire, relationship_name: RelationshipName, target: HolonReferenceWire) -> Result<(), MapErrorWire>;
    fn remove_relationship(&self, source: HolonReferenceWire, relationship_name: RelationshipName, target: HolonReferenceWire) -> Result<(), MapErrorWire>;

    fn delete_holon(&self, local_id: LocalId) -> Result<(), MapErrorWire>;
    fn load_holons(&self, bundle: HolonReferenceWire) -> Result<LoadHolonsResultWire, MapErrorWire>;
}

/// Lookup facade execution targets (normative).
pub trait TransactionLookupExecution {
    fn get_all_holons(&self) -> Result<HolonCollectionWire, MapErrorWire>;
    fn get_staged_by_base_key(&self, key: MapString) -> Result<Option<HolonWire>, MapErrorWire>;
    fn get_staged_by_versioned_key(&self, key: MapString) -> Result<Option<HolonWire>, MapErrorWire>;
    fn get_transient_by_base_key(&self, key: MapString) -> Result<Option<HolonWire>, MapErrorWire>;
    fn get_transient_by_versioned_key(&self, key: MapString) -> Result<Option<HolonWire>, MapErrorWire>;
    fn staged_count(&self) -> Result<u64, MapErrorWire>;
    fn transient_count(&self) -> Result<u64, MapErrorWire>;
    fn get_space_holon(&self) -> Result<Option<HolonReferenceWire>, MapErrorWire>;
}

/// Dance execution targets (normative).
pub trait TransactionDanceExecution {
    fn invoke_readonly(&self, dance_name: MapString, body: PropertyMap, options: Option<DanceInvokeOptionsWire>) -> Result<DanceResultWire, MapErrorWire>;
    fn invoke_mutating(&self, dance_name: MapString, body: PropertyMap, options: Option<DanceInvokeOptionsWire>) -> Result<DanceResultWire, MapErrorWire>;
}

/// Holon runtime surface for holon-scoped read commands (normative).
/// In practice, these resolve via HolonReferenceWire.bind(tx) -> HolonReference runtime -> methods.
pub trait HolonReadExecution {
    fn read_holon(&self, reference: HolonReferenceWire) -> Result<Option<HolonWire>, MapErrorWire>;
    fn get_related_holons(&self, reference: HolonReferenceWire, relationship_name: RelationshipName) -> Result<Vec<HolonReferenceWire>, MapErrorWire>;
    fn get_all_related_holons(&self, reference: HolonReferenceWire) -> Result<Vec<HolonReferenceWire>, MapErrorWire>;
}