mako-engine

Event-sourced process runtime for German energy market communication (MaKo).

The core runtime that all domain crates (mako-gpke, mako-wim, mako-geli-gas, …) build on. Provides event sourcing, optimistic-concurrency event storage, regulatory-deadline scheduling, outbox-based AS4 delivery, and process-state projections.

Architecture

Raw EDIFACT bytes (AS4 transport)
        │
        ▼
[edi-energy] parse · validate
        │
        ▼  Command (typed, validated)
EngineContext::spawn / ::resume → Process::execute
        │
        ├─ load events → reconstruct state (Workflow::apply)
        ├─ handle command (Workflow::handle — pure, deterministic)
        └─ append EventEnvelope batch (optimistic concurrency)

EventStore   ──► ProjectionRunner  ──► Read models
SnapshotStore ──► Process::state_with_snapshot (O(k) replay)
OutboxStore  ──► delivery worker   ──► AS4 endpoint
DeadlineStore ──► scheduler        ──► TimeoutDeadline command
PidRouter    ──► inbound routing   ──► Process

Key traits and types

Quick start

use mako_engine::{
    builder::EngineBuilder,
    ids::TenantId,
    version::WorkflowId,
    event_store::InMemoryEventStore,
};

let ctx = EngineBuilder::new()
    .with_event_store(InMemoryEventStore::new())
    .build();

// Spawn a new process for one conversation.
let process = ctx.spawn::<MyWorkflow>(TenantId::new(), WorkflowId::new("wf-id", "FV2025-10-01"));
let envelopes = process.execute(my_command).await?;

// Reconstruct typed state by replaying all events.
let state = process.state().await?;

// Resume on the next inbound message.
let identity = ctx.registry().lookup(tenant, &conv_id).await?.unwrap();
let resumed  = ctx.resume::<MyWorkflow>(identity);

Implementing a workflow

use mako_engine::error::WorkflowError;
use mako_engine::workflow::{Workflow, WorkflowOutput};

pub struct MyWorkflow;

impl Workflow for MyWorkflow {
    type Command = MyCommand;
    type Event   = MyEvent;
    type State   = MyState;

    /// Pure function — rebuild state from one event at a time.
    fn apply(state: Self::State, event: &Self::Event) -> Self::State {
        // state transition here
    }

    /// Pure function — no I/O, no clock, no global state.
    fn handle(
        state: &Self::State,
        command: Self::Command,
    ) -> Result<WorkflowOutput<Self::Event>, WorkflowError> {
        // business logic here
    }
}

A WorkflowOutput carries the events and the outbox messages they imply. The outbox half is only persisted when the command is dispatched through Process::execute_and_enqueue; plain Process::execute ignores it. An empty output is how a workflow says "already processed" — a no-op, not an error.

handle() and apply() must be pure. All parsing, validation, and I/O happens at the transport boundary before a command is constructed.

Feature flags

Regulatory deadlines

Deadlines are scheduled through DeadlineStore; the numbers never live beside a call site. Every business answer window comes from one table, mako_fristen::antwort, keyed on the inbound Prüfidentifikator:

antwortfrist returns None for a PID the Festlegungen do not quantify. That is unknown, never unbounded and never "no deadline".

Two clocks sit outside that table and are deliberately separate:

• the APERAK technical acknowledgement — 45 minutes on a Werktag (mako_fristen::aperak_strom_due_at), with its own Gas variants;
• an INVOIC answer, which counts back from the Zahlungsziel the invoice itself carries (SG8 DTM+265) rather than forward from receipt — that one is mako_fristen::vorlauf.

Saturday is not a Werktag. GPKE (BK6-24-174) Teil 1: "alle Tage ..., die kein Samstag, Sonntag oder gesetzlicher Feiertag sind". A holiday observed in any single Bundesland counts nationwide, and 24.12. and 31.12. count as holidays. Deadline arithmetic uses German local time (CET/CEST) via the time crate.

Dual-write atomicity

Events and outbox entries are written in a single WriteBatch via AtomicAppend::append_with_outbox. Never write events first and outbox second — a crash between the two produces a lost APERAK with no recovery path.

Format-version coexistence

WorkflowVersionPolicy::ForwardCompatible (the default for all MaKo workflows) allows a process started under FV2025-10-01 to continue under those rules after the FV2026-10-01 cutover. Do not use Pinned as default.

Related crates

Part of mako, an open-source Rust platform for German energy market communication (Marktkommunikation). Full documentation: https://hupe1980.github.io/mako/