Tutorial: Hello

This tutorial walks through the smallest Strata program accepted by the source-to-runtime gate.

The complete source is examples/hello.str.

Module

module hello;

The module declaration names the source unit. It does not import anything and does not create a package boundary.

State And Message Types

record MainState;
enum MainMsg {
    Start,
}

MainState is a fieldless record. It gives the process a concrete state type without carrying data.

MainMsg declares the messages accepted by Main. Start is the first variant, so it is the entry message delivered to Main when Mantle starts the program.

Main Process

proc Main mailbox bounded(1) {
    type State = MainState;
    type Msg = MainMsg;
    ...
}

Every runnable program needs a Main process. The mailbox bound limits how many messages can wait in the process mailbox.

The State alias points to the process state type. The Msg alias points to the process message enum.

Initial State

fn init() -> MainState ! [] ~ [] @det {
    return MainState;
}

init takes no parameters and returns the initial state. It uses no effects, has no may-behaviors, and is deterministic.

Step Function

fn step(state: MainState, Start) -> ProcResult<MainState> ! [emit] ~ [] @det {
    emit "hello from Strata";
    return Stop(state);
}

step receives the process state and handles the Start message named in its parameter pattern.

The body emits text and then returns Stop(state). Passing state preserves the supplied state while stopping normally.

The effect list is [emit] because the body uses exactly one effect.

Run It

cargo build
cargo run -p strata --bin strata -- check examples/hello.str
cargo run -p strata --bin strata -- build examples/hello.str
cargo run -p mantle-runtime --bin mantle -- run target/strata/hello.mta

The program prints:

hello from Strata

Mantle also writes:

target/strata/hello.observability.jsonl

That trace should contain artifact_loaded, process_spawned, message_accepted, message_dequeued, program_output, and process_stopped events.

Common Edits

If you remove emit "hello from Strata";, also change the effect list from [emit] to []. Declaring an unused effect is rejected.

If you add a second message variant to MainMsg, add a step clause for that variant or use one _ clause for variants without explicit clauses. Each accepted message must resolve to exactly one clause.