Crate mfm_machine 

Public API contract for the MFM runtime.

mfm-machine defines the stable identifiers, execution-plan types, context and IO abstractions, and storage interfaces used throughout the workspace. Runtime implementations live in unstable submodules such as runtime and live_io, while the types in this file model the architectural contract described in docs/redesign.md.

Example

use async_trait::async_trait;
use mfm_machine::context::DynContext;
use mfm_machine::errors::{ContextError, StateError};
use mfm_machine::ids::{ContextKey, OpId, StateId};
use mfm_machine::io::IoProvider;
use mfm_machine::meta::{DependencyStrategy, Idempotency, SideEffectKind, StateMeta, Tag};
use mfm_machine::plan::{ExecutionPlan, StateGraph, StateNode};
use mfm_machine::recorder::EventRecorder;
use mfm_machine::state::{SnapshotPolicy, State, StateOutcome};
use serde_json::Value;
use std::sync::Arc;

struct ExampleState;

#[async_trait]
impl State for ExampleState {
    fn meta(&self) -> StateMeta {
        StateMeta {
            tags: vec![Tag("report".to_string())],
            depends_on: Vec::new(),
            depends_on_strategy: DependencyStrategy::Latest,
            side_effects: SideEffectKind::Pure,
            idempotency: Idempotency::None,
        }
    }

    async fn handle(
        &self,
        _ctx: &mut dyn DynContext,
        _io: &mut dyn IoProvider,
        _rec: &mut dyn EventRecorder,
    ) -> Result<StateOutcome, StateError> {
        Ok(StateOutcome {
            snapshot: SnapshotPolicy::OnSuccess,
        })
    }
}

struct NullContext;

impl DynContext for NullContext {
    fn read(&self, _key: &ContextKey) -> Result<Option<Value>, ContextError> {
        Ok(None)
    }

    fn write(&mut self, _key: ContextKey, _value: Value) -> Result<(), ContextError> {
        Ok(())
    }

    fn delete(&mut self, _key: &ContextKey) -> Result<(), ContextError> {
        Ok(())
    }

    fn dump(&self) -> Result<Value, ContextError> {
        Ok(serde_json::json!({}))
    }
}

let _context = NullContext;
let plan = ExecutionPlan {
    op_id: OpId::must_new("portfolio_snapshot"),
    graph: StateGraph {
        states: vec![StateNode {
            id: StateId::must_new("machine.main.report"),
            state: Arc::new(ExampleState),
        }],
        edges: Vec::new(),
    },
};

assert_eq!(plan.op_id.as_str(), "portfolio_snapshot");

Source of truth: docs/redesign.md Appendix C.1.

Modules

canonical

Marker traits for canonical JSON hashing policy.

config

Run configuration types that shape execution, replay, and provenance behavior.

context

Context traits for reading, mutating, and snapshotting state-machine data.

engine

Engine traits and input/output types for starting or resuming runs.

errors

Structured error types used by state handlers, storage layers, and the engine.

events

Event types emitted by the engine and by state handlers during a run.

exec_transport

Unstable live IO transport for external program execution (exec namespace).

hashing

Internal helpers for canonical JSON hashing and ArtifactId computation.

ids

Stable identifier types shared by manifests, plans, events, and persisted records.

io

IO request and response abstractions used by live and replay providers.

live_io

Unstable Live IO implementation (facts recording).

live_io_registry

Unstable Live IO transport registry (runtime wiring).

live_io_router

Unstable Live IO transport router (namespace dispatch).

meta

Metadata used to classify states and express recovery or idempotency intent.

plan

Types that represent the executable state graph for a run.

process_exec

Unstable shared process execution helpers for live IO transports.

recorder

Traits for recording operation-defined domain events during state execution.

replay_io

Unstable Replay IO implementation (facts replay).

runtime

Unstable v4 runtime implementation (executor + resume logic).

state

State trait and outcome types used by planned execution nodes.

stores

Storage traits for append-only events and immutable artifacts.