Five Ways to Fail a Transport

(Ruuk shares syntax with F#. A brief introduction to F# is provided here if you need it.)

As a tech lead, I'd set minimum standards for API error handling — every call covers 400, 401, 403, 500. In ticket reviews I'd still find three failure scenarios in the notes and one in the code. Developers had spotted the cases; the language gave them nowhere permanent to put that knowledge.

The knowledge of which errors to handle was always there. It lived in tickets, in team standards, in code comments — and it degraded, because none of those places were connected to the compiler.

I started designing op because I wanted that knowledge to have a durable home in the code itself — a declaration that names every outcome an operation can produce, enforced at every call site. The first article in this series argued that this intent already exists in every codebase — in Javadoc, in JSDoc comments, in OpenAPI response schemas — but lives where the compiler can't see it. op moves it into the declaration.

The Binary Split

Every mainstream approach to error handling asks the same question first: did it work, or didn't it? Try/catch, Result, sealed exception hierarchies — they all partition outcomes into two buckets. If your background is Java or C#, you've reached for this with custom exception hierarchies or result wrapper classes — the intent is always the same: name the failure modes, make them visible to callers. But the binary framing works only when an operation genuinely has one way to succeed and one way to fail. This isn't always the best way to model many domain operations.

The previous article ended with a transporter that uses F#'s Result type:

type TransporterFailure =
    | SignalLost of lastCoords: string
    | PatternDegradation of integrity: float
    | TargetShielded

let beamUp target =
    if target.SignalStrength > 0.8 then
        Ok target.Name
    elif target.SignalStrength > 0.4 then
        Error (PatternDegradation target.SignalStrength)
    else
        Error (SignalLost target.LastKnownCoords)

The discriminated union inside Error means the failure modes are typed and named. Pattern matching means you can handle each one. This is genuinely good — I prefer it to exception hierarchies, or status codes. But three properties of the binary model compound at scale, regardless of which language you use.

New outcomes slip through the cracks. Add InsufficientPower to the transporter. In Java, callers that catch the base TransporterException still compile. In C#, a switch with a default arm still compiles. In F#, callers that forward the Error side with Result.map still compile. The call sites that explicitly enumerate cases will break — as they should — but the ones that handle errors generically don't. That's the pattern I saw as a tech lead. Developers would identify an error case during implementation, document it, and move on — and nothing in the toolchain pushed back. What if the compiler could make this impossible?

Success is more than one thing. Every binary error model — try/catch, Result<T, E>, Go's (value, error) — gives you exactly one success channel. But many domain operations have more than one meaningful success path. An upsert either created a new record or updated an existing one. A negotiation reached a full agreement or a provisional ceasefire. Both outcomes are successes, but they require different handling. Model two success paths and you're either misclassifying one as a failure or nesting another dispatch layer inside the success channel, where callers can process the value without ever distinguishing between the two paths.

This is the constraint we rarely notice: working in languages where success is modeled as singular can train us not to see cases where it isn't.

Outcomes are peers, not subcategories. Even in the best case — F#'s pattern matching, where the compiler verifies every arm — the binary structure leaks into every call site:

match beamUp target with
| Ok name -> $"Transport complete. {name} is aboard."
| Error (SignalLost coords) -> $"Signal lost at {coords}."
| Error (PatternDegradation integrity) -> $"Pattern at {integrity}."
| Error TargetShielded -> "Cannot beam through shields."

The domain has four outcomes; the type has two. Every failure arm spells out Error (...) as a preamble before reaching the actual case. The same ceremony appears in Java sealed hierarchies, C# result wrappers, and Go error returns. The wrapper changes; the two-bucket structure doesn't — and it shows everywhere the code touches the result.

Parameter intent is implicit. A real transporter operation has a target, a source location, a destination pad, and an operator. Most languages handle this with positional parameters or named arguments — beamUp(target, surface, pad, operator) or beamUp(target: riker, from: surface). Named arguments are a real improvement over positional-only. But the names are ad hoc: one operation uses from, another uses source, a third uses origin. Nothing enforces consistency across the codebase, and the compiler doesn't verify that a parameter labeled from actually plays the role of a source.

These properties are fine for small codebases where a team can hold the conventions in working memory. They compound as the number of operations and call sites grows — particularly in agentic workflows where the code is written by one system and reviewed by another.

What a Better Approach Could Look Like

These properties point toward three design criteria:

All outcomes must be handled at every call site. F#'s match and Java's switch expressions on sealed types already enforce exhaustive coverage — that's strong, and it's the right foundation. The remaining gap is call sites that forward, transform, or ignore the result without matching. When someone adds a sixth outcome, every call site should break until it's handled — not just the ones that happen to use match.

Outcomes should be peers, not wrapped. An operation that can produce five results should declare five outcomes at the same level. SignalLost is not a sub-category of "error" — it's a domain result as legitimate as Transported. The caller should handle each one directly, without unwrapping a success or error container first.

Parameters should carry semantic roles. Named parameters are good. A small, fixed vocabulary of parameter roles is better. If every operation in the codebase uses from to mean "source" and to to mean "destination" — not because of a naming convention, but because the language defines those roles and the compiler verifies them — then call sites are consistent by construction. A developer who learns the role vocabulary once can read any operation's call site without checking its signature.

This matters for agentic coding too. Language models trained on natural language have already internalized from and to as directional roles. A fixed vocabulary gives a model the same reference point as the human reviewer — generated call sites are consistent not by training luck, but by structural constraint.

Introducing op

Ruuk's op keyword declares a domain operation as a first-class language construct. A domain operation is any action with outcomes that callers need to handle differently — a database write, an API call, a state transition, a validation check. Pure transformations and internal helpers stay as regular let functions.

Here's the transporter. pub marks the operation as visible to other modules — the same access modifier you'd find in Rust:

pub op beamUp =
    payload target: CrewMember
    from surface: PlanetarySurface
    to pad: TransporterPad
    by operator: CrewMember
    outcomes =
        | Transported of CrewMember
        | SignalLost of lastCoords: String
        | PatternDegradation of integrity: Float
        | TargetShielded
        | InsufficientPower

Five outcomes, declared as peers. Each carries its own data — SignalLost carries coordinates, PatternDegradation carries an integrity reading, TargetShielded and InsufficientPower carry nothing. No outcome is privileged as "success" or "error" — each is a peer-level domain result.

The parameters have roles. payload marks the main data argument. from, to, and by are prepositions that describe each parameter's relationship to the operation. These aren't arbitrary labels chosen by the developer — they're drawn from a small, fixed vocabulary that Ruuk defines: payload, subject, from, to, by, via, in, at, for. Every operation in every codebase uses the same words for the same meanings.

The roles appear at the call site:

beamUp riker from planetSurface to padOne by laForge

Read it out loud: "beam up Riker from the planet surface to pad one by La Forge." Many languages have named parameters. The fixed role vocabulary adds consistency across the entire codebase — you don't learn source on one operation and origin on another. Every operation that takes something from somewhere uses from. Swap from and to and the compiler rejects it — TransporterPad is not a PlanetarySurface. The vocabulary is small enough to memorize in minutes, and once you know it, every call site reads the same way.

The op declaration is the contract. It tells every other module what beamUp needs and what it can produce. The implementation is a separate let binding:

let beamUp (target: CrewMember) (surface: PlanetarySurface)
           (pad: TransporterPad) (operator: CrewMember) =
    if pad.powerLevel < minimumPower then
        InsufficientPower
    elif surface.shielded then
        TargetShielded
    elif target.signalStrength > 0.8 then
        Transported target
    elif target.signalStrength > 0.4 then
        PatternDegradation target.signalStrength
    else
        SignalLost target.lastKnownCoords

The separation is deliberate. From another module, you read the op declaration — the contract — which tells you what to provide, what role each argument plays, and what can come back. The implementation is an internal detail. This is the three-party model from the first article in practice: the human defines the declaration, the agent generates the implementation body, and the compiler verifies that the body satisfies the contract.

Handling Outcomes with |> on

Outcomes are handled with |> on, which integrates directly into Ruuk's pipeline syntax:

beamUp riker from planetSurface to padOne by laForge
|> on Transported crew   -> printfn $"Transport complete. {crew.name} is aboard."
|> on SignalLost coords  -> printfn $"Signal lost at {coords}. Dispatching shuttle."
|> on PatternDegradation integrity ->
    printfn $"Pattern integrity at {integrity}. Boosting signal."
|> on TargetShielded     -> printfn "Cannot beam through shields. Hailing target."
|> on InsufficientPower  -> printfn "Rerouting power to transporter systems."

Each |> on arm matches one outcome and binds its data. Transported crew binds the returned CrewMember to crew. SignalLost coords binds the coordinates. TargetShielded carries no data, so there's no binding.

Compare this to the Result matching from earlier. The outcomes are flat — one level, five arms, each handled directly. There's no Ok/Error wrapper to spell out on every arm. The pipeline reads top to bottom: the operation produces a result, and each rail leads to its own destination.

If you've encountered Scott Wlaschin's railway-oriented programming, this is the same mental model extended from two rails to N — reflecting the actual structure of domain operations rather than forcing them through a binary split.

Exhaustive Handling

F# match already fails to compile when an arm is missing — that's the foundation op builds on. The difference is what happens when a developer reaches for a wildcard:

match beamUp target with
| Ok name -> $"Transport complete. {name} is aboard."
| Error (SignalLost coords) -> $"Signal lost at {coords}."
| Error (PatternDegradation integrity) -> $"Pattern at {integrity}."
| _ -> "Something went wrong."  // compiles; TargetShielded silently swallowed

This compiles. The wildcard arm satisfies the compiler while silently discarding any outcome it matches. |> on has no equivalent. Remove an arm and there's nowhere for that outcome to go:

beamUp riker from planetSurface to padOne by laForge
|> on Transported crew   -> printfn $"Transport complete. {crew.name} is aboard."
|> on SignalLost coords  -> printfn $"Signal lost at {coords}."
|> on PatternDegradation integrity -> printfn $"Pattern at {integrity}."
|> on TargetShielded     -> printfn "Cannot beam through shields."
-- InsufficientPower is missing

This does not compile:

Unhandled outcome: InsufficientPower
  in beamUp call at TransporterRoom.rk:14

Every declared outcome must be handled or explicitly marked as deferred. There's no catch-all to hide behind.

The practical consequence: if you add a new outcome to beamUp — say WarpFieldInterference because the ship is about to jump to warp — the compiler produces an error at every call site that doesn't handle it or explicitly mark it as deferred. That error list is your work queue. The decision can't be deferred silently.

Progressive Development with todo

If you've worked under schedule pressure — and you have — you might see a tension with exhaustive handling. The compiler now requires every outcome to be accounted for before the code compiles. But the whole motivation for op was that schedules don't leave room to handle everything at once. Demanding completeness on day one would just trade one problem for another.

todo resolves this. It's the developer's explicit acknowledgment to the compiler: I know this outcome needs handling. Not today.

beamUp riker from planetSurface to padOne by laForge
|> on Transported crew   -> printfn $"Transport complete. {crew.name} is aboard."
|> on SignalLost coords  -> printfn $"Signal lost at {coords}."
|> on PatternDegradation integrity -> printfn $"Pattern at {integrity}."
|> on TargetShielded     -> todo
|> on InsufficientPower  -> todo

This compiles. The compiler emits warnings — "todo: TargetShielded outcome unhandled at line 5" — but not errors. If TargetShielded fires at runtime, todo panics with a clear message pointing to the unhandled outcome and its location.

todo works anywhere an expression is expected. In a function body you haven't implemented yet. In a match arm you'll fill in later. In a pipeline handler you're deferring. Every todo in the codebase is a compiler-tracked work item. The warnings list is your checklist; the compiler maintains it automatically.

This is the difference that mattered to me: without a declaration like op, unhandled error paths can become invisible — they compile silently, and under schedule pressure, the team moves on. With op and todo, the sprint can end with incomplete handling, but every gap is tracked, visible, and named. That visibility is just as critical in agentic workflows — an agent that generates an implementation can't silently skip an outcome, and a reviewer scanning todo warnings sees exactly which decisions remain open. A language should be a feedback system during development, not just a gatekeeper at the end.

A Richer Example: Routing Emergency Power

The transporter demonstrates outcomes and parameter roles. A more complex operation shows how they compose.

During a Red Alert, Engineering needs to reroute power from non-essential systems to critical ones — shields, weapons, life support. But a reroute isn't all-or-nothing: the holodeck might spare 300 units without shutting down completely, even when 500 were requested. The operation has two distinct success paths and several failure paths:

pub op routePower =
    payload amount: PowerUnits
    from source: ShipSystem
    to target: ShipSystem
    by officer: CrewMember
    outcomes =
        | FullyRouted of PowerAllocation
        | PartiallyRouted of PowerAllocation
        | InsufficientPower of available: PowerUnits
        | SystemOffline of system: ShipSystem
        | OverloadRisk of currentLoad: Float
        | UnauthorizedAccess

At the call site, the roles make the operation self-documenting:

routePower 500 from holodecks to shields by laForge

"Route 500 power units from holodecks to shields by La Forge." A developer cold-reading this code doesn't need the signature to tell which system gives power and which receives it.

Chaining this with the alert status makes a realistic pipeline:

pub op setAlertStatus =
    payload status: AlertStatus
    by officer: CrewMember
    outcomes =
        | AlertSet of AlertStatus
        | AlreadyAtStatus
        | InsufficientRank

setAlertStatus Red by picard
|> on AlertSet _ ->            -- discard the AlertStatus value
    routePower 500 from holodecks to shields by laForge
    |> on FullyRouted alloc ->
        printfn $"Power rerouted: {alloc.amount} units to shields."
    |> on PartiallyRouted alloc ->
        printfn $"Partial reroute: {alloc.amount} units to shields. Requesting auxiliary power."
    |> on InsufficientPower available ->
        printfn $"Only {available} units available. Requesting auxiliary power."
    |> on SystemOffline system ->
        printfn $"Cannot draw from {system.name}: system offline."
    |> on OverloadRisk load ->
        printfn $"Shield grid at {load}% capacity. Reroute would overload."
    |> on UnauthorizedAccess ->
        printfn "Officer lacks authorization for power routing."
|> on AlreadyAtStatus ->
    printfn "Already at Red Alert."
|> on InsufficientRank ->
    printfn "Only senior officers can set alert status."

The nesting mirrors the domain logic. You can only reroute power after setting the alert succeeds — and each level handles its own outcomes completely. The compiler verifies coverage at both levels independently.

FullyRouted and PartiallyRouted are both successes — the power moved — but they require different responses. With Result, expressing two success paths means either misclassifying one as an error or wrapping both in another union inside Ok, where callers can ignore the distinction. With op, both sit at the top level as peers, and the compiler holds every call site to both.

The Comparison

The argument for op is not that functions-returning-unions are wrong. They're a good pattern — better than exceptions, better than status codes, better than unchecked error returns. op builds on that foundation by making the properties structural rather than advisory:

F# provides the foundation op builds on — exhaustive matching, typed unions, immutable data. The table highlights the specific gaps that remain when Result is the primary abstraction for domain operations: call sites that forward or ignore results aren't covered by exhaustive checking, the binary split can obscure domain structure, and parameter semantics depend on naming conventions. op is Ruuk's attempt to close those gaps.

When to Use op vs let

Not everything is a domain operation. op is for actions with multiple outcomes that callers handle differently — service calls, state transitions, validations. Pure transformations, utility functions, and internal helpers stay as regular let functions. If a function has one return path with no alternative outcomes, let is the right tool. The parameter roles offer a practical test: if payload, from, to, and the rest don't fit naturally, the operation probably isn't a domain action — it's a transformation.

What's Next

op builds on F#'s strengths — exhaustive matching, typed unions, immutable data — and addresses the gaps this series cares about. Parameter roles replace ad hoc naming conventions. The binary Ok/Error split gives way to peer-level outcomes. And exhaustive handling extends from match expressions to every call site. The declaration carries it all, and the compiler enforces it everywhere. That's the foundation the rest of the series builds on.

But the declaration doesn't yet control what each operation can see or when it can run.

The next article introduces projections — type-level views that control which fields an operation can access. If the transporter's beamUp operation shouldn't see a crew member's medical records, that restriction should be structural, not a runtime filter somebody remembers to apply. Projections make information boundaries part of the type system.

After that: typestate, where the compiler tracks what state an entity is in and prevents operations that don't make sense in that state. You shouldn't be able to beam someone up who hasn't been cleared for transport — and the type system should enforce that, not a runtime guard.

The transporter is a single operation. Real starship procedures chain dozens of them, and when step five fails, steps one through four may need to be undone. That's the saga article. But first, we need to control what operations can see and when they can act.

Ruuk is pre-alpha. If these ideas resonate, follow along on GitHub and weigh in on the discussions.