States, Transitions, Effects: What a `.gu` File Actually Buys

The previous post made the case for Gust as a workflow contract.

This one is more concrete.

Abstract language posts are cheap. The more useful question: what does a .gu file buy that ordinary code doesn't?

Right now the answer is:

• one place to read the workflow contract
• explicit state data
• enumerated transitions
• generated host-language boundary code
• declared side effects
• a cleaner runtime integration point

That's the practical value.

Gust isn't useful because it has syntax. It's useful only if the syntax preserves information the rest of the system needs.

Workflow code has been relying on convention for decades. The .gu file is what stops being conventional.

A workflow file is a contract

Here's the declaration portion of the order notification workflow Corsac uses as its canonical example (handler bodies come later):

type OrderPayload {
    order_id: String,
    customer: String,
    total_cents: i64,
    currency: String,
    items_count: i64,
}

machine OrderNotificationWorkflow {
    state Idle
    state WebhookReceived(body: String, source_ip: String)
    state OrderParsed(order: OrderPayload, original_body: String)
    state MessageFormatted(order: OrderPayload, slack_text: String, original_body: String)
    state NotificationSent(order_id: String, slack_ts: String)
    state Failed(step: String, reason: String, original_body: String)
    state DeadLettered(original_body: String, attempts: i64)

    transition receive: Idle -> WebhookReceived
    transition parse: WebhookReceived -> OrderParsed | Failed
    transition format: OrderParsed -> MessageFormatted | Failed
    transition notify: MessageFormatted -> NotificationSent | Failed
    transition retry: Failed -> WebhookReceived | DeadLettered
    transition reset: NotificationSent -> Idle

    effect parse_order_json(body: String) -> OrderPayload
    effect format_slack_message(order: OrderPayload) -> String
    action post_slack(channel: String, text: String, credential_id: String) -> String
    effect log_failure(step: String, reason: String) -> ()
    effect compute_retry_eligible(step: String, attempt: i64) -> bool
}

Even before reading any handler bodies, this file says a lot.

It says the workflow has an Idle state. It says a webhook carries body and source_ip. It says a parsed order carries the parsed order and the original body. It says a failed workflow can retry back to WebhookReceived or move to DeadLettered.

That information often exists in regular code. It's just rarely this visible.

What each state actually carries

One thing I like about state machines is that they force a basic question: what data exists at this point?

In a normal implementation, the answer can be muddy. A function might receive a large context object. A database row might have nullable columns for every step. A job payload might accumulate fields over time. By month six, the answer to "what data exists at this point" is "let me grep for it."

In a Gust machine, each state declares its own data:

state WebhookReceived(body: String, source_ip: String)
state OrderParsed(order: OrderPayload, original_body: String)
state MessageFormatted(order: OrderPayload, slack_text: String, original_body: String)

Data threading is now visible.

The original_body field isn't glamorous, but it matters. It exists because retry needs to reconstruct WebhookReceived.

That's the kind of detail that disappears when the workflow is just a pile of handlers.

With explicit state data, the workflow contract tells the runtime what can be serialized, inspected, resumed, and displayed.

Transitions, not status strings

The transition list answers another important question: where can the workflow go next?

transition parse: WebhookReceived -> OrderParsed | Failed
transition format: OrderParsed -> MessageFormatted | Failed
transition notify: MessageFormatted -> NotificationSent | Failed
transition retry: Failed -> WebhookReceived | DeadLettered

This is the difference between status as a string and state as a contract.

If status is just a string, a caller can write any value it wants. The runtime might not know the value is invalid until much later. If transitions are declared, the compiler and generated code can reject movement that doesn't fit the machine.

That doesn't solve every runtime problem. It removes a class of accidental states — the ones that get created by a careless update and discovered by a customer.

What handlers make first-class

Handlers attach logic to transitions:

on format(ctx: OrderParsedCtx) {
    let text = perform format_slack_message(ctx.order);
    goto MessageFormatted(ctx.order, text, ctx.original_body);
}

on notify(ctx: MessageFormattedCtx) {
    let ts = perform post_slack("#orders", ctx.slack_text, "cred-slack-prod");
    goto NotificationSent(ctx.order.order_id, ts);
}

This is where the workflow moves from declaration to behavior.

The handler says what data it reads from the current state, what side effects it performs, and where it transitions next.

The important part isn't that this is shorter than Rust or Go. Sometimes it is, sometimes it isn't. The important part is that the workflow-specific pieces are first-class:

• perform names a declared effect or action
• goto names a declared target state
• ctx is tied to the source state of the transition

Those are workflow concepts. They should be visible in the workflow source.

Effects define the host boundary

Gust doesn't implement the actual Slack call. It declares that the machine needs one:

action post_slack(channel: String, text: String, credential_id: String) -> String

The generated host-language code then exposes a boundary the runtime must implement.

In Rust, this becomes an effect trait shape. In Go, it becomes an interface shape. The exact generated code varies by target, but the idea is the same: the workflow contract names the side-effectful call and the host application provides the implementation.

This is one of the main reasons I prefer code generation here.

The generated code is boring boundary code: state shapes, transition methods, invalid-transition errors, serialization, effect interfaces, target-language type mappings. The kind of code I want to exist, but don't want to hand-maintain across every workflow.

The .gu file stays focused on the workflow contract. The generated code does the repetitive host-language work.

Two snippets from other Gust machines show the shape. (The order notification workflow's full generated code runs to several hundred lines — same patterns, too long to inline.) Here's a Rust effect trait that preserves the side-effect categories as code comments:

pub trait WorkflowEngineEffects {
    /// gust:effect -- replay-safe / idempotent
    fn execute_step(&self, step_name: &str) -> String;
    /// gust:effect -- replay-safe / idempotent
    fn needs_approval(&self, step_name: &str) -> bool;
    /// gust:effect -- replay-safe / idempotent
    fn next_step_name(&self, current_step: &str) -> String;
    /// gust:effect -- replay-safe / idempotent
    fn produce_failure(&self, reason: &str) -> EngineFailure;
    /// gust:action -- not replay-safe / externally visible
    fn notify_rejection(&self, step_name: &str, reason: &str) -> String;
}

And a Go target that becomes the state and handler boundary you'd otherwise maintain by hand:

type OrderProcessorEffects interface {
    // gust:effect -- replay-safe / idempotent
    CalculateTotal(order Order) Money
    // gust:effect -- replay-safe / idempotent
    ProcessPayment(total Money) Receipt
    // gust:effect -- replay-safe / idempotent
    CreateShipment(order Order) string
}

func (m *OrderProcessor) Charge(effects OrderProcessorEffects) error {
    if m.State != OrderProcessorStateValidated {
        return &OrderProcessorError{Transition: "charge", From: m.State.String()}
    }

    receipt := effects.ProcessPayment(m.ValidatedData.Total)
    m.State = OrderProcessorStateCharged
    // state data update omitted
    return nil
}

That's the payoff: the source contract turns into the host-language shapes a runtime or application can actually call.

The action keyword compiles to the same host-language shape as effect today, but it means something different to a runtime. The gust:action marker says this call is externally visible — not safe to repeat on replay. Gust enforces a small but meaningful safety rule around it: a handler shouldn't perform more than one action, and the action should be the last side-effectful step before the transition. I'll go deeper on that boundary in a later post. For this one, the point is that the .gu file gives a runtime a signal that handwritten code wouldn't carry.

The compiler becomes a workflow reviewer

The compiler can catch simple mistakes that are easy to miss in hand-written workflow code:

• a transition points at an unknown state
• a handler goes to a state that isn't a declared target
• a perform call has the wrong number of arguments
• a goto passes the wrong number of fields
• a handler has code paths that don't end in a transition
• an action is followed by more side-effectful work

That doesn't replace tests. It doesn't replace runtime validation. It gives the edit loop a better reviewer than convention alone.

What the .gu file buys

A .gu file is useful if it becomes the shared source of truth for multiple consumers:

• the compiler
• generated Rust or Go code
• runtime dispatch
• validation tooling
• diagrams
• schema generation
• eventually a visual designer

That's the bigger point.

I don't want a workflow definition, a UI graph, a worker implementation, a runtime config file, and a docs page each inventing their own version of the workflow. I want the typed contract to sit underneath those surfaces.

That's what Gust is trying to provide.

Not magic. Not a general platform. A compact workflow contract that produces the boring code and metadata the rest of the system needs.

The next question is whether that contract can actually be operated. That's where Corsac begins.