DEV Community: Brock Claussen

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

Brock Claussen — Wed, 20 May 2026 13:00:00 +0000

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.

Why I'm Building a Typed Workflow Language Instead of Writing Glue Code

Brock Claussen — Wed, 13 May 2026 13:00:00 +0000

Post 1 was the diagnosis: workflow logic keeps wanting to be more structured than ordinary glue code, but less heavy than a full workflow platform. The contract is hiding in the implementation, and that's where the production incidents come from.

This one is about what should replace it.

I didn't want to start by building a control plane. I wanted the map first.

A way to describe a workflow as a contract:

these are the states
these are the transitions
this is the data each state carries
these are the side effects
these are the committed actions
this is the code the host application must provide

Then I wanted that contract to compile into boring, ordinary code.

That's the shape of Gust: a typed state-machine language that currently compiles to Rust and Go.

From code path to contract

A small workflow can start as a straightforward code path:

func HandleOrder(ctx context.Context, payload Payload) error {
    order, err := parseOrder(payload.Body)
    if err != nil {
        return markFailed("parse", err)
    }

    message := formatSlackMessage(order)

    if err := postSlack(ctx, message); err != nil {
        return markFailed("notify", err)
    }

    return markComplete(order.ID)
}

There's nothing obviously wrong with this function. For a small feature, it might be exactly the right code.

But as the workflow grows, the contract gets harder to see.

Where are the states? Which errors can retry? What data exists after parse but before notify? Is postSlack safe to repeat? If the process dies after posting but before marking complete, what should happen? Can a caller skip directly from received to notified? Does the UI know the same states the worker knows?

You can answer those questions with discipline, tests, comments, and docs. Those answers live outside the workflow itself. Six months later they live in someone's head. A year later they don't live anywhere.

Gust exists because I want the workflow contract to carry those answers directly.

Why not just JSON or YAML?

One possible answer is a declarative graph format. Put the states and edges in JSON or YAML, then let a runtime interpret the graph.

That can work. It's also the direction many workflow tools naturally take.

The tradeoff is that a graph file usually becomes another runtime input rather than a typed contract. The interesting behavior moves somewhere else: custom handler code, embedded expressions, loosely typed payloads, stringly named effects, runtime-only validation. You end up debugging a graph by guessing what the runtime did with it, which is the exact problem we were trying to escape.

Gust is trying to keep the contract closer to code without making the workflow disappear into ordinary application functions. The workflow stays explicit enough to validate and generate from, but it compiles into host-language code that Rust and Go projects can own.

That's the middle ground I want. More structure than glue code. Less platform gravity than a full interpreted workflow engine.

What a Gust machine says explicitly

Here's what that looks like in source. A Gust workflow is a state machine:

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)

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

    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
}

That file isn't an implementation detail. It's the contract.

It says which states exist. It says which transitions are allowed. It says what data is available in each state. It says which side-effectful calls the host runtime must implement. It says which operation is an externally visible action.

Handler bodies fill in the transition logic, but the shape above is already useful. The compiler can validate pieces of that contract before the runtime ever sees it.

Why compile instead of interpret?

I didn't want the first version of Gust to be a giant runtime.

That matters. Runtimes attract scope. Once the runtime owns everything, every design question becomes a platform question. Every feature request becomes a hosted product feature request. That's a different project, with a different burn rate, and I'm not ready to commit to that project yet.

The current approach is deliberately conservative: Gust compiles .gu source into host-language code. Rust output gets enums, machine structs, transition methods, effect traits, and serialization support. Go output gets state constants, state data structs, transition methods, interfaces, and JSON tags.

That keeps the generated code close to the systems I already want to run. It also makes Gust useful as a companion language rather than a replacement for Rust or Go. The host application still owns real I/O, credentials, deployment, observability, and business integrations. Gust owns the workflow contract and the generated state-machine layer.

That split matters. It keeps the language smaller and makes adoption less all-or-nothing. Pulling Gust out later — if it doesn't earn its keep — should be a deletion, not a migration.

Effects are part of the interface

The most important part of the language might not be the state syntax. It's the effect boundary.

In Gust, side effects are declared:

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

The generated code requires the host runtime to provide implementations for those calls.

Which means the workflow doesn't secretly talk to Slack, the database, or an HTTP API. The contract names the call. The runtime binds it.

The newer action distinction exists for workflow runtimes like Corsac. A runtime can treat normal effect calls as replay-safe or non-committing, while treating action calls as externally visible work that must not be repeated casually.

That's the kind of contract glue code usually leaves implicit. Implicit is fine until the day a payment gets charged twice and someone has to explain it on a call.

What the compiler can catch

Gust is at v0.2 — still young — but the compiler already applies useful validation pressure across three areas:

Structure: duplicate state and transition names, unknown states in transitions, unreachable states.
Flow: missing handlers, invalid goto targets, mismatched goto argument counts, branch termination warnings.
Safety: effect argument arity, selected expression type mismatches, action handler-safety warnings.

None of that makes workflow bugs impossible. But it moves basic contract mistakes out of the runtime path and into the edit/build loop.

That's the point.

I don't want to discover during a production run that a transition targets a state nobody declared, or that a handler can fall through without a state transition, or that a committed action is followed by more side-effectful work in the same path. Those bugs have always been catchable. They just usually weren't caught.

What Gust is and isn't

Gust isn't a hosted workflow product. It isn't a queue, scheduler, visual designer, deployment system, or run database. Those are runtime and product concerns. Corsac is where I'm exploring some of that operational surface.

It also isn't trying to replace Rust or Go. The host language still matters. The generated code should feel like code you could have written, but didn't want to maintain by hand. A small language has to justify every feature it adds, because every feature is one more thing to teach, document, and not regret.

The long-term question is how far Gust should go. It can stay a focused state-machine DSL and still be valuable. The current roadmap leaves room for a broader direction — free functions, stronger type checking, contracts, effect polymorphism, more owned semantics instead of passing work to target-language compilers — but I don't want to rush that. The useful thing right now is narrower: prove that typed workflow contracts can generate real code, support real tooling, and give a runtime like Corsac enough structure to operate compiled workflows.

That's why I'm building a typed workflow language instead of writing more glue code. The glue code still exists. It just moves to the boundary where it belongs: effect implementations, runtime adapters, deployment scripts, product-specific integrations.

The next post walks through what a .gu file actually buys, line by line.

The Workflow Problem That Made Me Stop Trusting Glue Code

Brock Claussen — Tue, 05 May 2026 20:45:52 +0000

A few years ago I watched a webhook handler charge a customer's card twice in the same minute. The success path committed. The retry path committed. They'd been written six months apart by different engineers, neither aware the other existed. The fix took an afternoon. The conversation about why the system allowed it took two weeks.

The fix was an idempotency key. The two weeks were about everything else.

I've been writing this kind of code for 20 years, and that incident wasn't the first or the worst. Across consulting gigs, Fortune 500 integrations, and products I've shipped, the same shape keeps showing up. A webhook comes in. A payload gets parsed. We enrich it with a customer record, call an API, post a notification, write a row, enqueue a follow-up job, and handle the error path if something goes wrong.

At first, it's just application code. A function here, a queue consumer there, a few retries, a few logs, maybe a database status column. It doesn't feel like a workflow system. It feels like the practical thing you write because the product needs to move.

That's the trap.

Useful workflows don't stay small. They grow branches. They get approval steps. They need retries. They need cancellation. They need to avoid charging a card twice or posting the same Slack message three times. They need to resume after a deploy, a crash, a timeout, or a handler bug. They need enough history that someone can answer a basic operator question: what happened to this run?

At that point, the workflow is no longer just glue code. It's a state machine. The only question is whether that state machine is explicit, or scattered through conditionals, database fields, queue messages, and side effects. In my experience it's almost always the second one.

The shape of the bug

The bugs that bother me most in workflow code aren't clever algorithm bugs.

They're state and boundary bugs:

A handler assumes a step already happened, but the persisted state doesn't prove it.
A retry repeats a side effect that should have been committed once.
A failure is stored as a string, so retry policy depends on text that was never meant to be a contract.
A function looks like a pure transform but quietly calls a database, an API, or a notification service.
A workflow can enter a state no caller expected because transitions are just convention.
The UI, worker, API, and deploy target each have a slightly different idea of what the workflow is.

I've been in the meeting where I asked "what state can this be in?" and got a 20-minute conversation involving three engineers and a database query.

None of those problems are exotic. That's what makes them annoying. They're the normal failure mode of workflow automation when the workflow model is implicit. The code can look clean locally. Each function reads fine in review. The system-level contract is still informal — and the informal part is exactly where the production incident is going to come from.

The hidden state machine

In the Marines, an operations order is a contract. It names the phases of the operation, the conditions to move between them, the abort criteria, what each element is doing in each phase, and what counts as mission complete. It isn't a vibe. It's a document everyone references when things start going sideways. Because things will start going sideways.

A workflow is the same kind of contract. It just doesn't usually look like one.

The double-charge incident I opened with had an implicit state machine. There were states — "received," "processing," "charged," "failed," "retried" — but none of them were named anywhere. They lived in a status column, a queue message, and a handful of conditionals. When the retry path was added, nobody wrote down the rule that "charged" was terminal. Nobody had to. The code worked.

Until it didn't.

If those states had been explicit, the questions would have answered themselves before shipping: What transitions are legal? Which state is terminal? Which step commits an externally visible action? Which failure states can retry?

When states are implicit, you still answer those questions. You just answer them at 2 AM, after the fact, distributed across code paths, database columns, log messages, and the heads of whoever wrote the code three sprints ago.

That's where glue code becomes expensive. Not because functions are bad. Not because JSON is bad. Because the workflow contract is hiding in the implementation instead of being something the implementation follows.

The side-effect problem

Workflows are mostly about side effects.

Parsing JSON isn't the hard part. The hard part is deciding what the runtime is allowed to repeat.

There's a real difference between these operations:

validate a payload
compute a retry decision
format a message
read a cached record
charge a card
send an email
post to Slack
write to an external system

In ordinary glue code, the line between which of those can replay safely and which can't is expressed by naming, comments, or reviewer discipline. Discipline doesn't save you when things go sideways. The runtime needs to know which calls are replay-safe and which calls are externally visible commitments — and it needs to know that without inferring it from a function name.

A workflow runtime needs a side-effect boundary it can reason about. If the contract doesn't say where committed work happens, the runtime is guessing from implementation details, and the customer is the one who finds out.

The bet

There are good workflow engines already. I'm not skeptical of them because durable-execution systems are useless. I'm skeptical because most of them put the runtime at the center of gravity. You describe a graph or write code against a framework, and the platform interprets or orchestrates the execution. That's a fine answer for a lot of teams. It isn't the answer I want as an engineer.

I want the workflow contract to be the source of truth, not the runtime.

A workflow should be readable before it's runnable. You should be able to open one file and see the states the workflow can be in, the transitions it allows, the data carried by each state, the side effects it can perform, the committed actions it might take, and the failure shape it exposes to the runtime. Then the generated code and operational tooling should preserve that contract instead of re-inventing it somewhere else.

That's why I stopped trusting workflow glue code as the primary abstraction. Not because glue code is always bad. Because workflows eventually need stronger boundaries than glue code naturally provides — and by the time you notice, you're already paying for it.

The next post is about what I'm building to fix it.