High-level transactions

The SDKs provide saga helpers for workflows that need compensation actions after a domain failure.

Each host call remains durable on its own. A saga registers compensations for successful steps and runs them in reverse order when a later step fails. Compensation is a new external action, not deletion of the earlier effect.

Sagas do not provide atomicity or isolation. Earlier calls and their compensations remain in history, and other tasks can observe effects before compensation runs.

The SDK provides support for two different types of transactions:

fallible transactions compensate failures and report the outcome
infallible transactions compensate failures and ask the host policy before appending a new attempt

Fallible transactions

A workflow can use compensations to counter earlier successful operations when a later operation fails. For example, a compensation can request a refund after a charge. It does not erase the charge or hide it from other tasks, and the compensation itself can fail.

A fallible transaction deals with domain errors. Successful steps register compensations. Propagating a domain error out of the transaction body triggers these compensations in reverse order; handling the error inside the body does not automatically trigger rollback. The failing step has no registered compensation. TypeScript, Rust, Scala and Go stop at the first compensation error and report partial rollback. Effect’s withFallibleCompensation continues the remaining compensations and reports the first compensation error.

TypeScript

In TypeScript, a fallible saga can be executed using the async fallibleSaga function, by passing an async callback that can execute operations on the open transaction (see below).

Effect TypeScript

In Effect TypeScript, wrap an Effect program with Saga.fallibleTransaction. Typed failures, caught defects and interruption trigger registered compensations. Complete rollback preserves the original Cause; partial rollback retains original and compensation failures. External cancellation terminates retries without losing this evidence.

Rust

In Rust, a fallible transaction can be executed using the async fallible_transaction function in golem_rust, by passing a closure wrapped with boxed(async move { ... }) that can execute operations on the open transaction (see below).

Scala

In Scala, a fallible transaction can be executed using Transactions.fallibleTransaction, by passing a Future-returning function that can execute operations on the open transaction (see below).

Go

In Go, a fallible transaction can be executed using the transaction.Fallible function of the github.com/golemcloud/golem/sdks/go/golem/transaction package, by passing a function that can execute operations on the open transaction (see below). A domain error returned from the body triggers the compensations, and the transaction returns a transaction.Failure[E]; rollback stops at the first compensation error, which is reported in its CompensationFailure field.

Infallible transactions

After each failed, fully compensated infallible attempt, the SDK resolves a host policy with verb saga, noun the agent URN, and attempt/error-kind properties. The host’s next-retry-delay uses the existing evaluator and an opaque binary continuation. SDKs carry that state unchanged and use durable clocks and timers. No matching policy selects the agent default. Unbounded policies are rejected rather than silently capped. Count/time/never exhaustion returns a typed guest failure; selector/evaluator errors retain the original failure too.

New attempts append calls and retain failed attempts and compensations. Bounds keep attempts finite; they do not rewind history. Reconstruction repairs an incomplete call at its original Start, without discarding sibling history. TS, Effect, Scala and Go compensate caught failures in reverse order. Fallible helpers propagate the original exception/panic only after complete rollback; partial rollback retains both failures. Effect external cancellation stops retries and preserves original and compensation evidence in Cause; self-interruption is policy-retryable. Rust WASM panic aborts without compensation. An uncatchable deterministic guest trap permanently fails the invocation; generic infrastructure retry handling is unchanged. MoonBit exposes the retry API but has no saga helper.

TypeScript

In TypeScript, an infallible saga can be executed using the async infallibleSaga function, by passing an async callback that can execute operations on the open transaction (see below).

Effect TypeScript

Saga.infallibleTransaction accepts a typed failure channel. Fully compensated failures, caught defects and self-interruption can be policy-retried; exhaustion, policy errors and partial rollback return SagaRetryFailure.

Rust

In Rust, an infallible transaction can be executed using the async infallible_transaction function in golem_rust, by passing a closure wrapped with boxed(async move { ... }) that can execute operations on the open transaction (see below). Return Result from the closure and handle the helper’s Result for compensation failure, exhaustion and policy errors.

Scala

In Scala, an infallible transaction can be executed using Transactions.infallibleTransaction, by passing a Future-returning function that can execute operations on the open transaction (see below).

Go

In Go, an infallible transaction can be executed using the transaction.Infallible function, by passing a function that can execute operations on the open transaction (see below). It returns a Result, including compensation failure, exhaustion and policy errors while retaining the original failure.

Operations

Both transaction types require the definition of operations.

It is defined with the following interface:

TypeScript


/**
* Represents a compensable step of the transaction.
*
* Implement this interface and use it within a saga block.
* Compensable steps can also be constructed with `compensable`.
*/
export interface Compensable<In, Out, Err> {
/**
 * The action to execute.
 * @param input - The input to the operation.
 * @returns A promise resolving to the result of the operation.
 */
execute(input: In): Promise<Result<Out, Err>>
/**
 * Compensation to perform in case of failure.
 * Compensations should not throw errors.
 * @param input - The input to the operation.
 * @param result - The result of the operation.
 * @returns A promise resolving to the result of the compensation.
 */
compensate(input: In, result: Out): Promise<Result<void, Err>>
}

There are two ways to define a compensable step:

Implement the Compensable interface manually
Use the compensable function to create one from a pair of closures


export function compensable<In, Out, Err>(
    execute: (input: In) => Promise<Result<Out, Err>>,
    compensate: (input: In, result: Out) => Promise<Result<void, Err>>,
): Compensable<In, Out, Err>

Effect TypeScript

Saga.operation creates a reusable Effect step. The compensation receives the input, successful output, and failure cause, and must have an infallible (never) error channel:


import { Effect } from "effect"
import { Saga } from "@golemcloud/effect-golem"
 
const op = Saga.operation({
  execute: (idx: number) => Effect.succeed(`id-${idx}`),
  compensate: (idx, id, _cause) =>
    Effect.log(`reverting ${id}, ${idx}`),
})

Use Saga.withFallibleCompensation instead when a compensation itself can fail.

Rust


 
/// Represents a compensable step of the transaction.
///
/// Implement this trait and use it within a `transaction` block.
/// Operations can also be constructed from closures using `operation`.
pub trait Operation: Clone {
    type In: Clone;
    type Out: Clone;
    type Err: Clone;
 
    /// Executes the operation which may fail with a domain error
    async fn execute(&self, input: Self::In) -> Result<Self::Out, Self::Err>;
 
    /// Executes a compensation action for the operation.
    async fn compensate(&self, input: Self::In, result: Self::Out) -> Result<(), Self::Err>;
}

There are two ways to define an operation:

Implement the Operation interface manually
Use the operation function to create an operation from a pair of closures


/// Constructs an `Operation` from two closures: one for executing the operation,
/// and one for rolling it back. The rollback operation always sees the input and
/// the output of the operation.
///
/// This operation can run the compensation in both fallible and infallible transactions.
pub fn operation<In: Clone, Out: Clone, Err: Clone>(
 execute_fn: impl Fn(In) -> Pin<Box<dyn Future<Output = Result<Out, Err>>>> + 'static,
 compensate_fn: impl Fn(In, Out) -> Pin<Box<dyn Future<Output = Result<(), Err>>>> + 'static,
) -> impl Operation<In = In, Out = Out, Err = Err> {
 FnOperation {
     execute_fn: Rc::new(execute_fn),
     compensate_fn: Rc::new(compensate_fn),
 }
}

Scala


trait Operation[-In, Out, Err] {
 
  def execute(input: In): Future[Either[Err, Out]]
 
  def compensate(input: In, output: Out): Future[Either[Err, Unit]]
}

There are two ways to define an operation:

Implement the Operation trait manually
Use the Transactions.operation function to create an operation from a pair of closures


def operation[In, Out, Err](
  run: In => Future[Either[Err, Out]]
)(
  compensate: (In, Out) => Future[Either[Err, Unit]]
): Operation[In, Out, Err]

MoonBit

The MoonBit SDK does not yet provide a high-level saga helper. Use ordinary async control flow with application callbacks for domain operations and their compensations. For example, an order workflow can reserve stock, charge a payment, and confirm the order. If a later step fails, refund the payment before releasing the stock.

This application-defined outcome keeps the original failure and any failed compensations. An empty compensation-error array means that every attempted compensation succeeded, not that the external systems provide an atomic rollback.


///|
enum OrderOutcome {
  Confirmed
  Failed(String, Array[(String, String)])
}

Go


// Operation is a compensable step: an action paired with the rollback to undo it.
// compensate receives both the original input and the output execute produced.
type Operation[In, Out, E any] struct {
    // unexported fields
}

An operation is created with transaction.NewOperation from a pair of functions. Domain errors are the error arm of a golem.Result:


func NewOperation[In, Out, E any](
    execute func(In) golem.Result[Out, E],
    compensate func(In, Out) golem.Result[golem.Unit, E],
) Operation[In, Out, E]

Executing operations

The defined operations can be executed in fallible or infallible mode:

TypeScript


import { compensable, fallibleSaga, infallibleSaga, Result } from "@golemcloud/golem-ts-sdk"
 
// example operation with compensation
const op = compensable<number, string, string>(
  async (idx) => {
    // the operation / side effect
    return Result.ok("id-" + idx)
  },
  async (idx, id) => {
    // compensation
    console.log(`reverting ${id}, ${idx}`)
    return Result.ok(undefined)
  }
)
 
// With fallibleSaga, errors are propagated using Result.
const resultFallible = await fallibleSaga(async tx => {
  const firstId = await tx.execute(op, 1)
  if (firstId.isErr()) return firstId
 
  const secondId = await tx.execute(op, 2)
  if (secondId.isErr()) return secondId
 
  return Result.ok([firstId.val, secondId.val])
})
 
const resultInfallible = await infallibleSaga(async tx => {
  const firstId = await tx.execute(op, 1)
  const secondId = await tx.execute(op, 2)
  return [firstId, secondId]
})

Effect TypeScript


import { Effect } from "effect"
import { Saga } from "@golemcloud/effect-golem"
 
const op = Saga.operation({
  execute: (idx: number) => Effect.succeed(`id-${idx}`),
  compensate: (idx, id, _cause) =>
    Effect.log(`reverting ${id}, ${idx}`),
})
 
// Construct an Effect program to yield from an agent method.
const resultFallible = Saga.fallibleTransaction(
  Effect.gen(function* () {
    const firstId = yield* op(1)
    const secondId = yield* op(2)
    return [firstId, secondId] as const
  }),
)

Rust


use golem_rust::{boxed, fallible_transaction, infallible_transaction, operation};
 
let op = operation::<i32, String, String>(
    |idx| boxed(async move { Ok(format!("id-{idx}")) }),
    |idx, id| {
        boxed(async move {
            println!("reverting {id}, {idx}");
            Ok(())
        })
    },
);
 
let result_fallible = fallible_transaction(|tx| {
    let op = op.clone();
    boxed(async move {
        let first_id = tx.execute(op.clone(), 1).await?;
        let second_id = tx.execute(op, 2).await?;
        Ok((first_id, second_id))
    })
})
.await;
 
let result_infallible = infallible_transaction(|tx| {
    let op = op.clone();
    boxed(async move {
        let first_id = tx.execute(op.clone(), 1).await?;
        let second_id = tx.execute(op, 2).await?;
        Ok((first_id, second_id))
    })
})
.await;

Scala


import golem.Transactions
 
import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue
 
val op = Transactions.operation[Int, String, String](
  idx => Future.successful(Right(s"id-$idx"))
)(
  (idx, id) => {
    println(s"reverting $id, $idx")
    Future.successful(Right(()))
  }
)
 
val resultFallible: Future[Either[Transactions.TransactionFailure[String], (String, String)]] =
  Transactions.fallibleTransaction[(String, String), String] { tx =>
    tx.execute(op, 1).flatMap {
      case Right(firstId) =>
        tx.execute(op, 2).map(_.map(secondId => (firstId, secondId)))
      case Left(error) =>
        Future.successful(Left(error))
    }
  }
 
val resultInfallible: Future[Either[Transactions.TransactionFailure[Any], (String, String)]] =
  Transactions.infallibleTransaction { tx =>
    for {
      firstId <- tx.execute(op, 1)
      secondId <- tx.execute(op, 2)
    } yield (firstId, secondId)
  }
// Handle Left outcomes for exhaustion, policy error or partial rollback.

MoonBit

The MoonBit SDK does not provide high-level saga helpers. Implement the saga with ordinary control flow and durable host calls.

The function below uses OrderOutcome from the previous example. The callbacks are application code, not SDK exports. Implement them with durable HTTP or RPC host calls. Each callback must return Err only when it knows that the requested effect did not occur; reconcile ambiguous remote outcomes before returning. Confirmation must not return Err after it commits the order.


///|
async fn place_order(
  order_id : String,
  reserve_stock : async (String) -> Result[String, String],
  charge_payment : async (String) -> Result[String, String],
  confirm_order : async (String) -> Result[Unit, String],
  refund_payment : async (String) -> Result[Unit, String],
  release_stock : async (String) -> Result[Unit, String],
) -> OrderOutcome {
  let reservation_id = match reserve_stock(order_id) {
    Ok(id) => id
    Err(error) => return Failed(error, [])
  }
  let mut payment_id : String? = None
  let original_error = match charge_payment(order_id) {
    Err(error) => error
    Ok(id) => {
      payment_id = Some(id)
      match confirm_order(order_id) {
        Ok(_) => return Confirmed
        Err(error) => error
      }
    }
  }
  let rollback_errors : Array[(String, String)] = []
  if payment_id is Some(id) {
    match refund_payment(id) {
      Ok(_) => ()
      Err(error) => rollback_errors.push(("refund payment", error))
    }
  }
  // Attempt stock release even if the refund failed.
  match release_stock(reservation_id) {
    Ok(_) => ()
    Err(error) => rollback_errors.push(("release stock", error))
  }
  Failed(original_error, rollback_errors)
}

This workflow handles returned domain errors. Raised errors propagate to the caller; they do not trigger this rollback path. It does not retry operations or failed compensations automatically. The caller must handle partial rollback explicitly, for example by recording the order for reconciliation instead of reporting that rollback completed.

Keep execute and compensation calls duplicate-safe, with stable application idempotency keys such as the order ID and an operation name. Ordinary local callbacks are not durable by themselves. Golem records supported host calls and replays their results during recovery; a crash reconstructs the recorded prefix and repairs eligible incomplete calls. It does not undo external effects or make a remote service idempotent.

Go


import (
    "fmt"
 
    "github.com/golemcloud/golem/sdks/go/golem"
    "github.com/golemcloud/golem/sdks/go/golem/transaction"
)
 
// example operation with compensation
var op = transaction.NewOperation(
    func(idx int32) golem.Result[string, string] {
        // the operation / side effect
        return golem.Ok[string, string](fmt.Sprintf("id-%d", idx))
    },
    func(idx int32, id string) golem.Result[golem.Unit, string] {
        // compensation
        fmt.Printf("reverting %s, %d\n", id, idx)
        return golem.Ok[golem.Unit, string](golem.Unit{})
    },
)
 
type Pair = golem.Tuple2[string, string]
 
// With Fallible, errors are propagated using golem.Result.
resultFallible := transaction.Fallible(func(tx *transaction.Tx[string]) golem.Result[Pair, string] {
    firstID := tx.Step(op, 1)
    if firstID.IsErr() {
        return golem.Err[Pair, string](firstID.Err())
    }
    secondID := tx.Step(op, 2)
    if secondID.IsErr() {
        return golem.Err[Pair, string](secondID.Err())
    }
    return golem.Ok[Pair, string](Pair{A: firstID.Ok(), B: secondID.Ok()})
})
 
// With Infallible, a returned error compensates and retries the whole transaction.
resultInfallible := transaction.Infallible(func(tx *transaction.Tx[string]) golem.Result[Pair, string] {
    firstID := tx.Step(op, 1)
    if firstID.IsErr() {
        return golem.Err[Pair, string](firstID.Err())
    }
    secondID := tx.Step(op, 2)
    if secondID.IsErr() {
        return golem.Err[Pair, string](secondID.Err())
    }
    return golem.Ok[Pair, string](Pair{A: firstID.Ok(), B: secondID.Ok()})
})

Both resultFallible and resultInfallible are golem.Result[Pair, transaction.Failure[string]].