Skip to content
XMachines

RFC: Run (v1)

Status: Draft
Version: v1
Scope: Machine execution, runs, events, ports, snapshots
Non-goals: Transport protocols, persistence backends

1. Purpose

This RFC defines what a run is and how machines execute in XMachines.

A run is the sole execution unit.

2. Core Concepts

2.1 Machine

A deterministic state transition system.

2.2 Run

A run is a single execution lineage of a machine.

Properties:

  • bound to exactly one machine
  • progresses only by events
  • history is immutable

2.3 Run Identity

  • Run IDs are opaque and hash-like
  • The algorithm is Git OID–compatible
  • With Git enabled: run ID is a commit hash
  • Without Git: the same algorithm is used

Run IDs never change and never require migration.

3. Lifecycle

3.1 Creation

  • forked from a machine
  • initial state only
  • no applied events

3.2 Progression

  • events are applied sequentially
  • batches are atomic (all-or-nothing)

3.3 Completion

  • completion is machine-defined
  • runs may remain open indefinitely

4. Ports

All ports are Web Streams.

in

WritableStream of events.
The only external mutation mechanism.

out

ReadableStream of outputs emitted by the machine.

err

ReadableStream of errors.

snapshot

ReadableStream of snapshots.

Snapshots are:

  • produced internally
  • observable externally
  • never writable or triggerable externally

5. Events

  • immutable
  • ordered
  • atomic
  • deterministic

6. Snapshots

Snapshots are materialized state views.

Rules:

  • optional
  • derived from events
  • never replace event history
  • represent latest truth

7. Determinism

Given the same machine and ordered event sequence, a run is deterministic.

8. Concurrency

  • single-writer semantics
  • concurrent senders serialize at in

9. Errors

  • errors are observable via err
  • fatality is machine-defined
  • errors do not mutate history

10. Invariants

  1. Events are the only mutation mechanism
  2. Snapshots are read-only externally
  3. History is immutable
  4. IDs are Git OID–compatible

11. Lock statement

A run is the execution of a machine driven solely by ordered events.
All interaction happens through streams.
This is Run v1.