Introduction

ORBIT is a declarative workflow language and a durable runtime for coordinating work across services written in different languages. You describe what should happen in a .orbit file: which tasks run, in which order, with which retries, timeouts and compensations. The compiler checks the whole workflow against typed task contracts before anything runs, and the runtime executes it durably, recording every decision as an event. Business logic stays in ordinary programs, called workers, written in Python, TypeScript, Go, Rust, Java or C#.

This page explains the problem ORBIT addresses, how its parts fit together, and what it guarantees.

The problem

A business process such as “validate an order, score its risk, reserve stock, charge the card, notify the customer” usually spans several services, often in several languages. Coordinating them by hand means writing the same infrastructure in every service: retry loops, timeouts, deduplication, state tables to survive restarts, and cleanup code for when a later step fails. That coordination logic ends up scattered, hard to review, and hard to reason about after a crash.

ORBIT moves the coordination into one place. The workflow file states the process and its policies. The runtime owns all workflow state and makes it survive crashes. Workers only implement individual tasks.

How the pieces fit

  order.orbit ──► orbit compiler ──► orbit-ir (typed, hashed JSON)
                   type checks,              │
                   dependency graph          │ orbit deploy / orbit run
                                             ▼
                                   ┌───────────────────┐
                                   │   orbit server    │  SQLite or PostgreSQL
                                   │ (durable runtime) │──► event history
                                   └─────────┬─────────┘
                       worker protocol (HTTP/JSON or gRPC)
                 ┌──────────┬───────────┼──────────┬──────────┐
              Python   TypeScript      Go        Rust     Java, C#
              worker     worker      worker     worker    workers

The CLI is a single binary, orbit, that contains the compiler, the runtime server, the formatter, the language server and the client commands.

A short example

A task contract declares the typed interface that a worker implements. A workflow composes tasks into steps:

task "greeting.compose" {
    version "1.0.0"
    input { name: String }
    output { message: String }
}

task "greeting.decorate" {
    version "1.0.0"
    input { message: String, excitement: Int }
    output { message: String }
}

workflow Hello {
    version "1.0.0"

    input {
        name: String
        excitement: Int = 3
    }

    output { greeting: String }

    step compose {
        worker "greeting.compose"
        using python
        with { name: input.name }
        retry { attempts: 3, backoff: exponential, initial_delay: 500ms }
    }

    step decorate {
        worker "greeting.decorate"
        using typescript
        with { message: compose.message, excitement: input.excitement }
        timeout 10s
    }

    return { greeting: decorate.message }
}

decorate reads compose.message, so it depends on compose and runs after it. compose is served by a Python worker and retried up to three times; decorate is served by a TypeScript worker and limited to 10 seconds per attempt. If decorate passed compose.messsage (a typo) or an Int where a String is required, orbit check would reject the file with a located error before anything is deployed.

The quick start runs this workflow end to end.

Guarantees

The runtime is event-sourced: every state change is an event committed to the database before it takes effect, and the state of an execution is rebuilt from its history after a restart. Tasks are delivered at least once, never “exactly once”. Each task carries an idempotency key that stays the same across retries and redeliveries, so workers can make side effects idempotent. When the outcome of an attempt is unknown, for example because a worker or the runtime crashed mid-task, the runtime redelivers the same attempt and still accepts a late result from the original delivery. Workflow definitions are immutable: name@version is bound to a content hash, and running executions keep the definition they started with. The compiler checks every step against its contract, and the runtime validates execution inputs and worker outputs against the same types. Delivery guarantees gives the precise rules.

Current scope

Workflows can wait for typed signals, answer typed queries, compute values without a worker, and run on failure, on cancel and on timeout handlers after compensation; see Signals and queries, Compute steps and Outcome handlers. orbit test runs workflow tests in-process with mocked tasks and simulated time, orbit simulate runs a workflow locally with mocked or generated results, and orbit replay checks a recorded history against the current decider; see Testing workflows, Simulation and Replay.

One server executes workflows at a time. For availability, several servers can share one PostgreSQL database in active/standby mode: one leader runs the engine, and a standby takes over if it stops. See Running several servers. The server can cap active executions, fan-out, history length and payload sizes, and can give applications client identities limited to some workflows; see Running the server and Security.

Next steps

• Installation: install the CLI, the runtime and an SDK.
• Quick start: create a project and run a workflow with Python and TypeScript workers.
• Core concepts: the vocabulary used throughout this documentation.
• Steps: the full syntax of a step.
• How workers work: the worker model and the SDKs.

Why ORBIT

ORBIT is for teams that want a business process to be a definition they can read, review, check and test as a whole, across services written in several languages. This page describes the problems it is built for, when another tool is a better fit, and how it compares with code-first durable execution engines such as Temporal.

The idea: the process is a typed contract

In ORBIT, a workflow is a declaration, not a program: which tasks run, in what order, under which conditions, with which retries and deadlines, how each side effect is undone, which human decisions it waits for, and what happens when it fails, is cancelled or times out. The compiler checks that declaration against the contracts of the services that do the work. That gives guarantees a process written as code does not have by default:

• Every service call matches its contract, in every language. A field renamed in a worker’s contract breaks the build, not production.
• Every declared side effect has an undo action. A task that declares compensated_by must be compensated wherever it is used (orbit check --strict).
• Every human decision is typed and every wait can be required to have a deadline.
• Every path is testable with test blocks that run in milliseconds, with time simulated.
• A change is reviewable: orbit compat reports breaking changes and the version bump they need, and running executions keep the version they started with.

What it is built for

Business processes you have to be able to explain

Onboarding and KYC, lending and underwriting, claims, refunds, orders, procurement. Processes where an auditor, a compliance officer or a product owner asks “what happens if…?” and the answer should be in one file, not spread across services. See Typed business process contracts.

Orchestration across services in several languages

One workflow can call workers in Python, TypeScript, Go, Rust, Java and C#, and the compiler checks every call against its contract, whatever language implements it. Teams keep their services in the language they chose; the process does not belong to any one of them. See Polyglot workflows.

Human-in-the-loop work

Approvals, reviews and exception handling, with typed decisions, deadlines, escalation and a record of who decided what. See Human approvals.

Sagas

Multi-step operations that must be undone in reverse when a later step fails: reserve, charge, ship. Compensation is declared per step and checked by the compiler; outcome handlers run after it. See Orders with compensation.

AI agents that must not run away

Durable tool calls with typed results, bounded fan-out, budgets, guardrail checks and human review. See AI agents with guardrails.

Small teams that want durability without a platform team

One binary. SQLite for development and small deployments, PostgreSQL for production, several servers when you need failover or more throughput. No separate history, matching and frontend services to run.

When to use something else

• The logic is genuinely algorithmic. Loops of unknown length, complex data structures, dynamic decisions about what to call next: these are natural in code and awkward in a declaration. A code-first engine fits better, or keep that logic in a worker and orchestrate around it.
• You need a managed service today. ORBIT has no hosted offering; you run it yourself.
• You need multi-region active-active execution, or Temporal-specific features such as Nexus, update handlers or worker build-ID versioning.
• Data pipelines and batch jobs with large datasets, where tools such as Airflow, Dagster or Spark are built for scheduling and data movement.

Compared with Temporal

Both record workflow history durably, recover by replaying it, deliver work to workers at least once, and support several languages. The difference is where the process lives: in Temporal it is code in one SDK language; in ORBIT it is a typed declaration checked against contracts in every language. The FAQ has a feature-by-feature table. In short:

Maturity

ORBIT is young. The runtime is tested end to end in six languages, with crash recovery, TLS, failover and several active servers, and the performance page shows measured numbers and what bounds them. It does not yet have years of production use. Read the delivery guarantees before you rely on it, and report what you find.

See also

• Core concepts
• Quick start
• FAQ and troubleshooting

Installation

ORBIT ships as one binary, orbit, that contains the compiler, the runtime server, the formatter, the language server and the client commands. You also install a worker SDK for each language your workers use. This page covers every installation method for the CLI and runtime, the six SDKs, the VS Code extension, upgrading and uninstalling.

The current release is v0.1.0.

Choose an installation method

The prebuilt Linux binaries link against glibc. On musl-based distributions such as Alpine, use cargo install or the Docker image.

Install script (Linux)

The install script downloads the release archive for your architecture, verifies its SHA-256 checksum against the release’s SHA256SUMS file, and installs the binary:

curl -fsSL https://github.com/AjmalX0/Orbit/releases/latest/download/install.sh | sh

orbit: downloading orbit-x86_64-unknown-linux-gnu.tar.gz (latest)
orbit: installed orbit 0.1.0 to /home/you/.local/bin/orbit

If the install directory is not on your PATH, the script prints orbit: add <dir> to your PATH. Add it in your shell profile, for example:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

The script reads these environment variables:

Pass them to sh, not to curl:

curl -fsSL https://github.com/AjmalX0/Orbit/releases/latest/download/install.sh \
  | ORBIT_VERSION=v0.1.0 ORBIT_INSTALL_DIR=/opt/orbit/bin sh

If the checksum does not match, the script prints orbit: checksum mismatch for <asset>, exits with status 1 and installs nothing.

Manual download (Linux)

To install without piping a script into sh, download the archive and the checksum file from GitHub Releases yourself:

curl -fsSLO https://github.com/AjmalX0/Orbit/releases/latest/download/orbit-x86_64-unknown-linux-gnu.tar.gz
curl -fsSLO https://github.com/AjmalX0/Orbit/releases/latest/download/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf orbit-x86_64-unknown-linux-gnu.tar.gz
install -m 0755 orbit ~/.local/bin/orbit

For arm64, use orbit-aarch64-unknown-linux-gnu.tar.gz. The archive contains the single orbit binary.

Windows

Download orbit-x86_64-pc-windows-msvc.zip from GitHub Releases, verify it, and put orbit.exe on your PATH. In PowerShell:

$base = "https://github.com/AjmalX0/Orbit/releases/latest/download"
Invoke-WebRequest "$base/orbit-x86_64-pc-windows-msvc.zip" -OutFile orbit.zip
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS

# Compare this hash with the orbit-x86_64-pc-windows-msvc.zip line in SHA256SUMS.
(Get-FileHash orbit.zip -Algorithm SHA256).Hash.ToLower()
Select-String "orbit-x86_64-pc-windows-msvc.zip" SHA256SUMS

$dir = "$env:LOCALAPPDATA\Programs\orbit"
Expand-Archive orbit.zip -DestinationPath $dir -Force
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$dir", "User")

Open a new terminal so that the updated PATH takes effect. The install script is a POSIX shell script and does not run in PowerShell or cmd.exe.

cargo install (any platform)

orbit-lang is the crate that provides the orbit binary. It builds on Linux, macOS and Windows with Rust 1.89 or later:

cargo install orbit-lang --locked

The build compiles the TLS stack from source, so it needs a C compiler and CMake in addition to Rust (on macOS, the Xcode command line tools and brew install cmake; on Debian and Ubuntu, apt install build-essential cmake). Cargo installs the binary into ~/.cargo/bin, which rustup adds to your PATH.

This is the recommended method on macOS: v0.1.0 has no prebuilt macOS binary.

Docker

The runtime image is published to the GitHub Container Registry:

The image runs orbit server as an unprivileged user, listens on 0.0.0.0:7233, and stores its SQLite database at /data/orbit.db (a volume). Because it listens on all interfaces, the server refuses to start without a token. Set ORBIT_TOKEN:

docker run -d --name orbit \
  -p 7233:7233 \
  -e ORBIT_TOKEN=change-me \
  -v orbit-data:/data \
  ghcr.io/ajmalx0/orbit:v0.1.0

Without a token, the container exits immediately with:

error: refusing to listen on 0.0.0.0:7233 without authentication; pass --token (or ORBIT_TOKEN), or --insecure for trusted networks

Use a long random token in practice; orbit token prints one. Clients and workers on the host then pass the same token:

export ORBIT_TOKEN=change-me
orbit ps

The image’s entry point is orbit, so arguments after the image name replace the default server command. For example, to print the version, or to start the server with the gRPC worker protocol (port 7234 is exposed for it) and the HTTP adapter enabled:

docker run --rm ghcr.io/ajmalx0/orbit:v0.1.0 --version

docker run -d -p 7233:7233 -p 7234:7234 -e ORBIT_TOKEN=change-me -v orbit-data:/data \
  ghcr.io/ajmalx0/orbit:v0.1.0 server --grpc-addr 0.0.0.0:7234 --enable-http-adapter

To build the image yourself from a clone, run docker build -t orbit . in the repository root. Deployment covers PostgreSQL, TLS and production settings.

From source

Build from a clone when you want unreleased changes or plan to contribute. You need Rust 1.89 or later, a C compiler and CMake:

git clone https://github.com/AjmalX0/Orbit.git
cd Orbit
cargo install --path crates/orbit-cli --locked

Alternatively, cargo build --release leaves the binary at target/release/orbit without installing it. Contributing describes the full development setup.

Verify the installation

Check the version:

orbit --version

orbit 0.1.0

Then start the runtime and query its health endpoint from a second terminal:

orbit server

curl -s http://127.0.0.1:7233/v1/health

{"status":"ok","api_version":"orbit-api/1","runtime_version":"0.2.0","ir_versions":["orbit-ir/1","orbit-ir/2"],"active_executions":0,"worker_sessions":0,"role":"single","node_id":null,"term":null,"leader":null}

By default orbit server listens on 127.0.0.1:7233 and creates orbit.db (plus orbit.db-wal and orbit.db-shm) in the current directory. Stop it with Ctrl-C.

Install a worker SDK

Workers use an SDK to register with the runtime, receive tasks and report results. Install the SDK for each language you write workers in:

The Python package is installed as orbit-lang-sdk and imported as orbit_sdk:

from orbit_sdk import Worker

For Java with Maven:

<dependency>
  <groupId>io.github.ajmalx0</groupId>
  <artifactId>orbit-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

With Gradle:

implementation("io.github.ajmalx0:orbit-sdk:0.1.0")

All SDKs read the same environment variables: ORBIT_SERVER (default http://127.0.0.1:7233), ORBIT_WORKER_TOKEN or ORBIT_TOKEN, ORBIT_CA_CERT, and ORBIT_CLIENT_CERT / ORBIT_CLIENT_KEY. Each language has its own page under Workers and SDKs.

Install the VS Code extension

The extension provides syntax highlighting and, through orbit lsp, diagnostics as you type, hover, go to definition, completion, outline and formatting. Download orbit-lang.vsix from GitHub Releases and install it:

curl -fsSLO https://github.com/AjmalX0/Orbit/releases/latest/download/orbit-lang.vsix
code --install-extension orbit-lang.vsix

The extension runs the orbit binary from your PATH. If it is installed elsewhere, set orbit.serverPath in your VS Code settings. The orbit.runtimeUrl setting (default http://127.0.0.1:7233) selects the runtime used by the extension’s Run and Deploy commands. See Editor support.

Upgrade

Stop the server before replacing its binary. On restart, the runtime reloads every definition and resumes every execution that was still running. Registered workflow definitions and execution history live in the database, not in the binary, so upgrading does not change them. The runtime reports the IR versions it accepts in /v1/health (ir_versions).

Uninstall

Remove the binary that matches how you installed it:

rm ~/.local/bin/orbit          # install script as a regular user
sudo rm /usr/local/bin/orbit   # install script as root
cargo uninstall orbit-lang     # cargo install

On Windows, delete %LOCALAPPDATA%\Programs\orbit and remove it from your user PATH.

For Docker, remove the container and, if you no longer need the data, the volume:

docker rm -f orbit
docker volume rm orbit-data
docker image rm ghcr.io/ajmalx0/orbit:v0.1.0

orbit server keeps its state in the database you pointed it at, by default orbit.db, orbit.db-wal and orbit.db-shm in the directory where you started it. Delete those files to remove all definitions and history.

Remove the VS Code extension with:

code --uninstall-extension orbit-lang.orbit-lang

Next steps

• Quick start: create a project and run your first workflow.
• Running the server: server options and storage.
• How workers work: the worker model and the SDKs.
• CLI reference: every orbit command.

Quick start

This tutorial takes you from an empty directory to a running workflow served by a Python worker and a TypeScript worker. You create a project with orbit init, run the runtime and the workers, start an execution, inspect its history, and then add a failure path to see retries and compensation at work. It takes about 15 minutes.

The outputs on this page come from real runs. Execution ids and timings differ on your machine.

Prerequisites

• The orbit CLI, version 0.1.0 or later. See Installation.
• Python 3.9 or later.
• Node.js 22.18 or later. The TypeScript worker is a .ts file that Node.js runs directly, without a build step.

You use three terminals: one for the runtime, one for each worker. Run every command from the project directory unless the step says otherwise.

1. Create a project

orbit init hello-orbit

  created hello-orbit/workers/typescript/package.json
  created hello-orbit/workers/python/requirements.txt
  created hello-orbit/.gitignore
  created hello-orbit/workflows/hello.orbit
  created hello-orbit/workers/python/worker.py
  created hello-orbit/workers/typescript/worker.ts
  created hello-orbit/README.md

Next: cd hello-orbit && orbit check workflows/hello.orbit

orbit init refuses to write into a directory that exists and is not empty. The project contains:

hello-orbit/
├── .gitignore
├── README.md
├── workflows/
│   └── hello.orbit            the workflow and its task contracts
└── workers/
    ├── python/
    │   ├── requirements.txt   orbit-lang-sdk>=0.1,<0.2
    │   └── worker.py          implements greeting.compose
    └── typescript/
        ├── package.json       depends on orbit-lang ^0.1.0
        └── worker.ts          implements greeting.decorate

2. Read the workflow

Open workflows/hello.orbit:

// A two-language hello world: Python composes, TypeScript decorates.

task "greeting.compose" {
    version "1.0.0"
    input { name: String }
    output { message: String }
}

task "greeting.decorate" {
    version "1.0.0"
    input { message: String, excitement: Int }
    output { message: String }
}

workflow Hello {
    version "1.0.0"

    input {
        name: String
        excitement: Int = 3
    }

    output { greeting: String }

    step compose {
        worker "greeting.compose"
        using python
        with { name: input.name }
        retry { attempts: 3, backoff: exponential, initial_delay: 500ms }
    }

    step decorate {
        worker "greeting.decorate"
        using typescript
        with { message: compose.message, excitement: input.excitement }
        timeout 10s
    }

    return { greeting: decorate.message }
}

The file has two parts:

• Task contracts. Each task declares a typed interface: a name, a contract version, an input and an output. Workers implement contracts; the compiler checks every step against them.
• A workflow. Hello takes a name and an optional excitement (default 3), runs two steps and returns a greeting. decorate reads compose.message, so it depends on compose and runs after it. using python and using typescript route each step only to workers of that language.

Type-check the file:

cd hello-orbit
orbit check workflows/hello.orbit

ok Hello@1.0.0 (2 steps)

3. Install the worker dependencies

Install the Python SDK into a virtual environment, and the TypeScript SDK with npm:

python3 -m venv .venv
. .venv/bin/activate
pip install -r workers/python/requirements.txt
(cd workers/typescript && npm install)

On Windows, activate the virtual environment with .venv\Scripts\activate.

4. Start the runtime

In the first terminal, from the project directory:

orbit server

INFO orbit: starting ORBIT runtime db=orbit.db backend="sqlite" http_adapter=false auth=false ui=true
INFO orbit_runtime::server: ORBIT runtime listening addr=127.0.0.1:7233 tls=false ui=true

The runtime listens on 127.0.0.1:7233 and stores everything in orbit.db in the current directory. Leave it running. Without a token it only accepts connections from the local machine; see Security before exposing it.

5. Start the workers

Each worker is an ordinary long-running program. It registers the contracts it implements and then long-polls the runtime for tasks.

Python worker

workers/python/worker.py implements greeting.compose:

"""Python worker for the Hello workflow.

Run:  pip install -r workers/python/requirements.txt
      python workers/python/worker.py
"""
from orbit_sdk import Worker

worker = Worker("hello-python")


@worker.task("greeting.compose", version="1.0.0")
def compose(input, ctx):
    ctx.log(f"composing a greeting for {input['name']}")
    return {"message": f"Hello, {input['name']}"}


if __name__ == "__main__":
    worker.run()

In the second terminal, activate the virtual environment and start it:

. .venv/bin/activate
python workers/python/worker.py

2026-11-15 09:34:37,324 INFO orbit worker hello-python registered (1 tasks)

TypeScript worker

workers/typescript/worker.ts implements greeting.decorate:

// TypeScript worker for the Hello workflow.
//
// Run:  (cd workers/typescript && npm install) && node workers/typescript/worker.ts
//       Node.js 22.18+ runs TypeScript directly.
import { Worker } from "orbit-lang";

const worker = new Worker({ workerId: "hello-typescript" });

worker.task<{ message: string; excitement: number }, { message: string }>(
  "greeting.decorate",
  { version: "1.0.0" },
  async (input) => ({ message: input.message + "!".repeat(input.excitement) }),
);

await worker.run();

In the third terminal:

node workers/typescript/worker.ts

[orbit] worker hello-typescript registered (1 tasks)

Both workers connect to http://127.0.0.1:7233 by default. Set ORBIT_SERVER to point them at another runtime.

Confirm that the runtime sees them. You can run client commands from any terminal; this tutorial uses the second one, but a fourth works as well:

orbit workers list

WORKER                       RUNTIME      STATE    INFLIGHT  TASKS
hello-python                 python       online   0  greeting.compose@1.0.0
hello-typescript             typescript   online   0  greeting.decorate@1.0.0

6. Run the workflow

orbit run workflows/hello.orbit --input '{"name": "Ada"}'

deployed Hello@1.0.0 (sha256:505930b4d466)
started execution 99e811dd-7448-41cc-ac28-bc58d50200d2
  ✓ compose                        succeeded 122ms
  ✓ decorate                       succeeded 140ms

COMPLETED 99e811dd-7448-41cc-ac28-bc58d50200d2  Hello@1.0.0
  elapsed: 269ms
{
  "greeting": "Hello, Ada!!!"
}

orbit run did three things:

1. Compiled and deployed the file. The runtime registered Hello@1.0.0 under the content hash sha256:505930b4d466.... Running the same file again prints up to date instead of deployed.
2. Started an execution with the input {"name": "Ada"}. The runtime applied the default excitement: 3 and validated the input against the workflow’s input type.
3. Followed the execution until it finished and printed the output.

orbit run exits with status 0 when the execution completes and 1 when it fails, so you can use it in scripts. Pass --no-wait to return right after the execution starts.

7. Inspect the execution

Every execution keeps its complete history. Use the execution id printed by orbit run (yours differs).

orbit status shows the outcome and one row per step:

orbit status 99e811dd-7448-41cc-ac28-bc58d50200d2

COMPLETED 99e811dd-7448-41cc-ac28-bc58d50200d2  Hello@1.0.0
  elapsed: 269ms

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  compose                      SUCCEEDED          1    122ms  worker hello-python
  decorate                     SUCCEEDED          1    140ms  worker hello-typescript

  output: {"greeting":"Hello, Ada!!!"}

orbit logs prints the event history as a timeline. These events are the authoritative record; the runtime rebuilds an execution’s state from them after a restart:

orbit logs 99e811dd-7448-41cc-ac28-bc58d50200d2

+     0ms   #1  WorkflowCreated
+     0ms   #2  WorkflowStarted
+     2ms   #3  StepScheduled             step=compose attempt=1
+     3ms   #4  StepDispatched            step=compose attempt=1 worker_id=hello-python
+   125ms   #5  StepSucceeded             step=compose attempt=1
+   127ms   #6  StepScheduled             step=decorate attempt=1
+   128ms   #7  StepDispatched            step=decorate attempt=1 worker_id=hello-typescript
+   268ms   #8  StepSucceeded             step=decorate attempt=1
+   269ms   #9  WorkflowCompleted

orbit inspect prints the full state as JSON, including each step’s input, output and idempotency key (abridged here):

orbit inspect 99e811dd-7448-41cc-ac28-bc58d50200d2

{
  "id": "99e811dd-7448-41cc-ac28-bc58d50200d2",
  "workflow": "Hello",
  "version": "1.0.0",
  "definition_hash": "sha256:505930b4d4668ff2f8cb95e04519d5292ef2fbf0630d575349aaf92c0e2b42be",
  "input": {
    "name": "Ada",
    "excitement": 3
  },
  "status": "COMPLETED",
  "units": {
    "compose": {
      "status": "SUCCEEDED",
      "attempt": 1,
      "input": {
        "name": "Ada"
      },
      "idempotency_key": "99e811dd-7448-41cc-ac28-bc58d50200d2/compose",
      "output": {
        "message": "Hello, Ada"
      },
      "redelivery": false,
      "worker_id": "hello-python",
      "tokens": "***"
    },
    "decorate": { "...": "..." }
  },
  "output": {
    "greeting": "Hello, Ada!!!"
  },
  "last_seq": 9
}

orbit ps lists recent executions:

orbit ps

EXECUTION                              WORKFLOW                 VERSION    STATUS        AGE
99e811dd-7448-41cc-ac28-bc58d50200d2   Hello                    1.0.0      COMPLETED     314ms

8. Add a failure path

Real workflows fail. In this step you add two steps and make the workers fail on purpose, so that you can see a retry, a permanent failure and a compensation.

• publish (Python) stores the greeting and returns a post_id. Its compensate block declares how to undo it: greeting.unpublish.
• notify (TypeScript) rejects messages longer than 40 characters with a non-retryable error.

Replace workflows/hello.orbit with the following. The version changes to 1.1.0; the next section explains why.

// A two-language hello world: Python composes, TypeScript decorates.

task "greeting.compose" {
    version "1.0.0"
    input { name: String }
    output { message: String }
}

task "greeting.decorate" {
    version "1.0.0"
    input { message: String, excitement: Int }
    output { message: String }
}

task "greeting.publish" {
    version "1.0.0"
    input { message: String }
    output { post_id: String }
}

task "greeting.unpublish" {
    version "1.0.0"
    input { post_id: String }
    output { removed: Bool }
}

task "greeting.notify" {
    version "1.0.0"
    input { post_id: String, message: String }
    output { delivered: Bool }
}

workflow Hello {
    version "1.1.0"

    input {
        name: String
        excitement: Int = 3
    }

    output { greeting: String, post_id: String }

    step compose {
        worker "greeting.compose"
        using python
        with { name: input.name }
        retry { attempts: 3, backoff: exponential, initial_delay: 500ms }
    }

    step decorate {
        worker "greeting.decorate"
        using typescript
        with { message: compose.message, excitement: input.excitement }
        timeout 10s
    }

    step publish {
        worker "greeting.publish"
        using python
        with { message: decorate.message }
        compensate {
            worker "greeting.unpublish"
            with { post_id: publish.post_id }
        }
    }

    step notify {
        worker "greeting.notify"
        using typescript
        with { post_id: publish.post_id, message: decorate.message }
    }

    return { greeting: decorate.message, post_id: publish.post_id }
}

Replace workers/python/worker.py. compose now fails its first attempt for names that start with Flaky, with a retryable error. publish uses the task’s idempotency key so that a redelivered task returns the same post instead of creating a second one:

import uuid

from orbit_sdk import TaskError, Worker

worker = Worker("hello-python")
posts = {}  # stands in for a database


@worker.task("greeting.compose", version="1.0.0")
def compose(input, ctx):
    # Simulate a flaky dependency: names starting with "Flaky" fail once.
    if input["name"].startswith("Flaky") and ctx.attempt == 1:
        raise TaskError("NAME_SERVICE_BUSY", "try again shortly", retryable=True)
    ctx.log(f"composing a greeting for {input['name']}")
    return {"message": f"Hello, {input['name']}"}


@worker.task("greeting.publish", version="1.0.0")
def publish(input, ctx):
    post_id = posts.get(ctx.idempotency_key) or f"post-{uuid.uuid4().hex[:8]}"
    posts[ctx.idempotency_key] = post_id
    ctx.log(f"published {post_id}")
    return {"post_id": post_id}


@worker.task("greeting.unpublish", version="1.0.0")
def unpublish(input, ctx):
    ctx.log(f"removed {input['post_id']}")
    return {"removed": True}


if __name__ == "__main__":
    worker.run()

Replace workers/typescript/worker.ts:

import { TaskError, Worker } from "orbit-lang";

const worker = new Worker({ workerId: "hello-typescript" });

worker.task<{ message: string; excitement: number }, { message: string }>(
  "greeting.decorate",
  { version: "1.0.0" },
  async (input) => ({ message: input.message + "!".repeat(input.excitement) }),
);

worker.task<{ post_id: string; message: string }, { delivered: boolean }>(
  "greeting.notify",
  { version: "1.0.0" },
  async (input) => {
    if (input.message.length > 40) {
      throw new TaskError("MESSAGE_TOO_LONG", `${input.message.length} characters`, { retryable: false });
    }
    return { delivered: true };
  },
);

await worker.run();

Stop both workers with Ctrl-C and start them again so that they register the new tasks. The Python worker now reports registered (3 tasks) and the TypeScript worker registered (2 tasks). Then check the workflow:

orbit check workflows/hello.orbit

ok Hello@1.1.0 (4 steps)

Why the version changed

Workflow definitions are immutable. If you had kept version "1.0.0", the runtime would reject the new content:

error: DEFINITION_CONFLICT (409): Hello@1.0.0 is already registered with a different definition (sha256:505930b4d4668ff2f8cb95e04519d5292ef2fbf0630d575349aaf92c0e2b42be); workflow definitions are immutable, bump the version

Bumping the version registers Hello@1.1.0 next to Hello@1.0.0. Executions that started on 1.0.0 keep running on 1.0.0. See Versioning.

Run the happy path

orbit run workflows/hello.orbit --input '{"name": "Grace"}'

deployed Hello@1.1.0 (sha256:c444589a24d2)
started execution c9bade94-bc35-4741-80a9-3a39780623d7
  ✓ compose                        succeeded 8ms
  ✓ decorate                       succeeded 7ms
  ✓ publish                        succeeded 10ms
  ✓ notify                         succeeded 6ms

COMPLETED c9bade94-bc35-4741-80a9-3a39780623d7  Hello@1.1.0
  elapsed: 45ms
{
  "greeting": "Hello, Grace!!!",
  "post_id": "post-71a73bf3"
}

Run the failure path

Now use a name that triggers the flaky compose, and enough excitement to make the message longer than 40 characters:

orbit run workflows/hello.orbit --input '{"name": "Flaky Grace", "excitement": 30}'

up to date Hello@1.1.0 (sha256:c444589a24d2)
started execution d599b57e-eee0-412e-b679-df8276005035
  ✓ compose                        succeeded 6ms
  ✓ decorate                       succeeded 4ms
  ✓ publish                        succeeded 4ms
  ✗ notify                         failed 48 characters
  ✓ compensate:publish             succeeded 6ms

FAILED d599b57e-eee0-412e-b679-df8276005035  Hello@1.1.0
  elapsed: 549ms
  compensation: completed
  error: MESSAGE_TOO_LONG step `notify` failed: 48 characters

The status table shows that compose needed two attempts:

orbit status d599b57e-eee0-412e-b679-df8276005035

FAILED d599b57e-eee0-412e-b679-df8276005035  Hello@1.1.0
  elapsed: 549ms
  compensation: completed
  error: MESSAGE_TOO_LONG step `notify` failed: 48 characters

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  compose                      SUCCEEDED          2      6ms  worker hello-python
  decorate                     SUCCEEDED          1      4ms  worker hello-typescript
  publish                      SUCCEEDED          1      4ms  worker hello-python
  notify                       FAILED             1      5ms  48 characters
  compensate:publish           SUCCEEDED          1      6ms  worker hello-python

The history records every decision:

orbit logs d599b57e-eee0-412e-b679-df8276005035

+     0ms   #1  WorkflowCreated
+     0ms   #2  WorkflowStarted
+     2ms   #3  StepScheduled             step=compose attempt=1
+     3ms   #4  StepDispatched            step=compose attempt=1 worker_id=hello-python
+     7ms   #5  StepAttemptFailed         step=compose attempt=1 error=NAME_SERVICE_BUSY try again shortly
+     8ms   #6  RetryScheduled            step=compose delay_ms=500
+   508ms   #7  StepScheduled             step=compose attempt=2
+   511ms   #8  StepDispatched            step=compose attempt=2 worker_id=hello-python
+   517ms   #9  StepSucceeded             step=compose attempt=2
+   518ms  #10  StepScheduled             step=decorate attempt=1
+   519ms  #11  StepDispatched            step=decorate attempt=1 worker_id=hello-typescript
+   523ms  #12  StepSucceeded             step=decorate attempt=1
+   524ms  #13  StepScheduled             step=publish attempt=1
+   526ms  #14  StepDispatched            step=publish attempt=1 worker_id=hello-python
+   530ms  #15  StepSucceeded             step=publish attempt=1
+   531ms  #16  StepScheduled             step=notify attempt=1
+   535ms  #17  StepDispatched            step=notify attempt=1 worker_id=hello-typescript
+   539ms  #18  StepAttemptFailed         step=notify attempt=1 error=MESSAGE_TOO_LONG 48 characters
+   540ms  #19  StepFailed                step=notify error=MESSAGE_TOO_LONG 48 characters
+   540ms  #20  CompensationStarted       reason=step `notify` failed: 48 characters
+   540ms  #21  StepScheduled             step=compensate:publish attempt=1
+   542ms  #22  StepDispatched            step=compensate:publish attempt=1 worker_id=hello-python
+   548ms  #23  StepSucceeded             step=compensate:publish attempt=1
+   549ms  #24  CompensationCompleted
+   549ms  #25  WorkflowFailed            error=MESSAGE_TOO_LONG step `notify` failed: 48 characters

Reading the timeline:

• Retry (#5 to #9). The first compose attempt failed with a retryable error. The step’s policy allows three attempts with exponential backoff starting at 500 ms, so the runtime waited 500 ms and dispatched attempt 2, which succeeded.
• Permanent failure (#18, #19). notify failed with retryable: false, so the runtime failed the step immediately, without using the remaining attempts. notify has no retry block, so it would have had only one attempt in any case.
• Compensation (#20 to #24). Because the workflow failed after publish succeeded, the runtime ran publish’s compensation, greeting.unpublish, with the post_id that publish returned. Steps without a compensate block (compose, decorate) have nothing to undo.
• Outcome (#25). The execution ended FAILED with compensation: completed: the failure was handled and the side effect was undone.

The Python worker’s output (timestamps removed) shows the failed attempt, the retry, and both sides of the compensation:

INFO orbit executing {"execution_id": "d599b57e-...", "step": "compose", "attempt": 1, "task": "greeting.compose", "redelivery": false}
INFO orbit task failed {"execution_id": "d599b57e-...", "step": "compose", "attempt": 1, "code": "NAME_SERVICE_BUSY"}
INFO orbit executing {"execution_id": "d599b57e-...", "step": "compose", "attempt": 2, "task": "greeting.compose", "redelivery": false}
INFO orbit composing a greeting for Flaky Grace {"execution_id": "d599b57e-...", "step": "compose", "attempt": 2}
INFO orbit executing {"execution_id": "d599b57e-...", "step": "publish", "attempt": 1, "task": "greeting.publish", "redelivery": false}
INFO orbit published post-2ce4c9b2 {"execution_id": "d599b57e-...", "step": "publish", "attempt": 1}
INFO orbit executing {"execution_id": "d599b57e-...", "step": "compensate:publish", "attempt": 1, "task": "greeting.unpublish", "redelivery": false}
INFO orbit removed post-2ce4c9b2 {"execution_id": "d599b57e-...", "step": "compensate:publish", "attempt": 1}

9. Clean up

Stop the workers and the runtime with Ctrl-C. All state is in orbit.db, orbit.db-wal and orbit.db-shm in the project directory; the project’s .gitignore already excludes them. Delete them to start from an empty runtime.

What you learned

• A workflow file declares typed task contracts and the steps that use them. orbit check validates it before anything runs.
• Workers in any language register contracts and pull tasks from the runtime.
• orbit run deploys and starts an execution; orbit status, orbit logs, orbit inspect and orbit ps show what happened and why.
• Retries are policy in the workflow, not code in the worker. A retryable: false error stops retrying at once.
• When a workflow fails, the runtime compensates the steps that succeeded, newest first.
• Definitions are immutable per version; changing a workflow means bumping its version.

Next steps

• Core concepts: precise definitions of the terms used here.
• Project layout: how to organize a larger project and use it in CI.
• Orders with compensation: a five-step order workflow with parallel steps, a condition and compensation.
• Retries and timeouts and Compensation: the full rules.
• Python and TypeScript and JavaScript: the SDK reference.

Core concepts

This page defines the terms used throughout the ORBIT documentation and shows how they relate. Each definition is precise about what the runtime does, so you can rely on it when you design workflows and workers.

Overview

 .orbit source                         runtime (orbit server)
 ─────────────                         ──────────────────────
 task contract ◄─── implemented by ─── worker (any language)
      ▲                                    ▲
      │ referenced by                      │ pulls tasks for
      │                                    │
 workflow ── compiled to ──► definition ── started as ──► execution
  └─ steps                    name@version                 ├─ units (one per step,
                              + content hash               │   fan-out element or
                                                           │   compensation)
                                                           ├─ history (events)
                                                           └─ child executions

A workflow is a set of steps. Each step calls a task contract, a child workflow, or a timer, waits for a signal, or computes a value. A workflow can also declare queries that report its state. Compiling a workflow produces a definition identified by name@version and a content hash. Starting a definition creates an execution. The runtime splits the execution into units, dispatches each task unit to a worker that implements the contract, and records every transition in the execution’s history.

Workflow

A workflow is a named, versioned declaration of a process: typed input, an optional typed output, a set of steps, and a return expression that maps step results to the output. Workflows contain no business logic and perform no I/O themselves. Every expression in a workflow is pure and deterministic, so every decision the runtime makes can be reproduced from history.

workflow Hello {
    version "1.0.0"
    input { name: String, excitement: Int = 3 }
    output { greeting: String }
    step compose { worker "greeting.compose" with { name: input.name } }
    return { greeting: compose.message }
}

See Workflows.

Task contract

A task contract (a task declaration) is the typed interface between a workflow and a worker: a name, a contract version, an input type and an output type.

task "greeting.compose" {
    version "1.0.0"
    input { name: String }
    output { message: String }
}

The compiler checks every step’s with block against the contract’s input, and every reference to a step’s output against the contract’s output. The runtime validates worker results against the output type again and fails the attempt with OUTPUT_CONTRACT_VIOLATION if they do not match.

Contracts are versioned independently of workflows. A worker receives a task only if it announced exactly that name@version. Names that start with orbit. are reserved for built-in tasks; there is one, orbit.http.request. See Task contracts.

Worker

A worker is a process you run, in any language with an SDK (Python, TypeScript, Go, Rust, Java, C#) or any program that speaks the worker protocol. It registers with the runtime under a worker id, announces the contracts it implements and its language runtime, long-polls for tasks, runs your handler, and reports a result or a structured error.

Workers hold no workflow state. You can run several workers for the same contracts to share load, and stop or restart them at any time: the runtime redelivers work whose outcome it never learned. A step with using python (or another language) is routed only to workers that registered with that runtime. See How workers work.

Step and unit

A step is a named node in a workflow. It does one of five things:

A step also declares its policies: dependencies (after), a condition (when), input (with), retry, timeout, queue_timeout, idempotency_key and compensate. A step depends on every step named in its after clause and on every step whose output it reads. Steps with no dependency between them run concurrently.

A unit is what the runtime actually schedules and tracks. Most steps are exactly one unit, keyed by the step name. Two cases create more:

Each unit has its own status, attempt counter, timeouts and idempotency key. A unit moves through PENDING → SCHEDULED → DISPATCHED → SUCCEEDED, or ends SKIPPED, FAILED or CANCELLED; it waits in RETRY_WAIT between attempts, in WAITING during a sleep or while waiting for a signal, and a fanned-out step is RUNNING while its elements execute. orbit status prints one row per unit. See Steps and Executions and history.

An attempt is one try at running a unit. retry { attempts: 3 } allows three attempts in total, including the first. A redelivery after an uncertain outcome reuses the same attempt number and does not count as a retry.

Signal

A signal is a typed message that a person or another system sends to a running execution, declared in the workflow with signal <name> { fields }. An await <name> step waits for the next signal of that name, durably, and its payload becomes the step’s output. The runtime validates every payload against the declaration before it records it, and buffers signals that arrive before a step waits for them, delivering them in order. Send one with orbit signal <id> <name> --data '{...}' or POST /v1/executions/{id}/signals/{name}. See Signals and queries.

Query

A query is a named, typed, read-only view of an execution’s state, declared with query <name> = <expression>. The runtime evaluates it on demand with orbit query <id> <name> or GET /v1/executions/{id}/queries/{name}, against the current input and step outputs; steps that have not succeeded read as null, and the compiler types every step output as optional in a query for that reason. A query records nothing and changes nothing. See Signals and queries.

Compute step

A compute step (compute <expression>) is a step that the runtime evaluates itself, with no worker: a deterministic expression over the input and earlier step outputs, whose value is recorded in the history as the step’s output. Use it for small data transformations between tasks, such as a total, a flag or a filtered list; lambdas (x => ...) with map, filter, find, any and all work on lists. See Compute steps.

Execution

An execution is one run of a definition with a specific input. It has an id (a UUID, or a client-chosen id passed with orbit run --id), a status, the state of each unit, and an output or error.

A finished execution that aborted also records compensation: none, completed or failed. Starting an execution with an id that already exists returns the existing execution instead of creating a second one.

History and events

The history of an execution is an append-only, ordered list of events, such as StepScheduled, StepDispatched, StepAttemptFailed, RetryScheduled and CompensationStarted. History is the authoritative state. The runtime commits events to the database before acting on them, rebuilds an execution’s state by replaying its events after a restart, and derives every decision from history through a pure function, so the same history always leads to the same decisions.

orbit logs <id> prints the history as a timeline; orbit logs <id> --json prints the raw events. See Executions and history.

Definition, version and hash

Compiling a workflow produces a definition in the intermediate representation (orbit-ir/1, or orbit-ir/2 for workflows that use signals, queries, await or compute steps, lambdas, on handlers or a limits block). Registering it with the runtime (orbit deploy, or implicitly orbit run) stores it under its name@version, together with a SHA-256 definition_hash of its semantic content.

• Source locations and formatting do not affect the hash, so reformatting a file changes nothing.
• Registering the same content again is a no-op (up to date).
• Registering different content under an existing name@version is rejected with DEFINITION_CONFLICT. To change a workflow, change its version.
• Each execution is pinned to the hash it started with. Deploying a new version never changes running executions.

See Versioning.

Idempotency key

Every task carries an idempotency key: a string that identifies the unit of work and stays the same across retries and redeliveries. By default it is <execution_id>/<unit>, for example 99e811dd-7448-41cc-ac28-bc58d50200d2/compose or order-A-4/reserve[1]. You can set your own with idempotency_key:, such as "charge-" + input.order_id, to deduplicate across executions.

The runtime evaluates the key once, when the unit is scheduled. Because delivery is at least once, a worker can receive the same task more than once; workers that cause side effects should use the key to perform them only once. See Idempotency and Delivery guarantees.

Compensation

A compensation is the business action that undoes a succeeded step, declared in the step’s compensate block. When an execution fails, is cancelled or times out, the runtime:

1. withdraws work that has not started,
2. waits for in-flight attempts to finish (they may still succeed),
3. runs the compensation of every succeeded unit that has one, one at a time, newest first.

Compensations are ordinary units (compensate:<unit>) with their own retries, timeouts and idempotency keys. They are explicit business logic, such as a refund or a release of reserved stock, not a database rollback. See Compensation.

Outcome handler

An outcome handler is a block of steps that runs once compensation has finished, when an execution fails (on failure), is cancelled (on cancel) or times out (on timeout), before the terminal status is recorded. Handler steps read a failure value (reason, code, message) and the outputs of the workflow steps that succeeded. Their units are on_<kind>:<step>, for example on_failure:tell_customer. A failing handler step does not change the execution’s outcome. See Outcome handlers.

Fan-out element

A for step (for item in input.items) runs its task once per list element. Each element is a separate unit, step[i], with its own retries, timeouts and idempotency key (<execution>/step[i]). At most max_parallel elements run at the same time. The step’s output is the list of element outputs in input order. The step succeeds when every element succeeds and fails when any element fails permanently; on compensation, each element that succeeded is compensated individually. See Fan-out.

Child execution

A workflow "Name" step starts another workflow as a child execution. The child has a deterministic id, <parent>.<step> (or <parent>.<step>.<i> inside a for step), so a crash or restart never starts it twice. The child is a full execution with its own history; orbit ps lists it and orbit status <parent>.<step> shows it. Its output becomes the step’s output. If the child fails, is cancelled or times out, the step fails, and cancelling the parent cancels its running children. See Child workflows.

How they relate

See also

• Quick start
• Steps
• Signals and queries
• Outcome handlers
• Delivery guarantees
• Executions and history
• Worker protocol

Project layout

This page describes what orbit init generates, how to organize a project as it grows, how imports work, how to change workflows and contracts safely, and how to check ORBIT sources in continuous integration.

What orbit init generates

orbit init my-project

orbit init creates the directory and seven files. It refuses to write into a directory that already exists and is not empty.

my-project/
├── .gitignore
├── README.md
├── workflows/
│   └── hello.orbit
└── workers/
    ├── python/
    │   ├── requirements.txt
    │   └── worker.py
    └── typescript/
        ├── package.json
        └── worker.ts

The quick start walks through running the generated project.

Recommended layout

As a project grows, keep contracts, workflows and workers apart. Contracts are shared by workflows and by the teams that write workers, so they deserve their own files:

my-project/
├── contracts/
│   ├── orders.orbit           schemas and tasks for one domain
│   └── payments.orbit
├── workflows/
│   ├── order_processing.orbit imports the contracts it uses
│   └── fulfilment.orbit
├── workers/
│   ├── python/                one directory per worker program
│   └── typescript/
└── .github/workflows/orbit.yml

Guidelines:

• Group contracts by domain (payments.*, inventory.*), and name tasks with a dotted prefix. Per-worker credentials grant access by pattern, such as payments.*, so a consistent prefix keeps those rules short.
• Keep one workflow per file when workflows are independent. Put a parent and the child workflows it starts in the same compilation, either in one file or through imports.
• Keep workers next to the contracts they implement, or in the repositories of the services that own them. Workers only need the contract names and versions; they do not read .orbit files.

The examples/ directory of the ORBIT repository follows this pattern on a small scale: examples/contracts.orbit holds shared contracts, and examples/order_processing.orbit and examples/fulfilment.orbit import it.

Imports

import brings another file’s declarations into the compilation. The path is resolved relative to the importing file:

// workflows/order_processing.orbit
import "../contracts/orders.orbit"
import "../contracts/payments.orbit"

workflow OrderProcessing {
    version "1.0.0"
    // ...
}

The rules:

• Every file is loaded once, even when several files import it, so two workflows can import the same contracts file.
• All declarations share one namespace. Declaring the same schema, task or workflow twice is an error (E0200).
• Declarations can appear in any order within and across files.
• A file that cannot be read is reported as E0206.

Pass the workflow files to the CLI; imported files are found automatically:

orbit check workflows/*.orbit

ok Bye@1.0.0 (1 steps)
ok Hello@1.0.0 (1 steps)

A file that contains only contracts checks as ok no workflows (contracts only). See Files and imports.

Versioning workflow changes

Definitions are immutable per name@version, and the runtime enforces it. Deploying changed content under a version that is already registered fails:

error: DEFINITION_CONFLICT (409): Hello@1.0.0 is already registered with a different definition (sha256:505930b4d4668ff2f8cb95e04519d5292ef2fbf0630d575349aaf92c0e2b42be); workflow definitions are immutable, bump the version

Reformatting a file or editing comments does not change the definition hash, so it never causes a conflict.

Changing a workflow

1. Edit the workflow and bump its version, for example from 1.0.0 to 1.1.0.
2. Run orbit check.
3. Deploy it with orbit deploy, or let orbit run deploy it.

Executions that already started keep running on the definition they started with. New executions use the version you ask for: orbit run <file> starts the version in the file, and orbit run <Name> --version <v> starts a specific registered version. orbit run <Name> without --version starts the highest registered version, compared numerically (1.10.0 is higher than 1.9.0).

Changing a task contract

Contract versions are independent of workflow versions. A worker receives a task only when it announced the same task name and contract version that the step uses.

• Compatible change (for example, a new optional output field that no workflow reads yet): you can keep the contract version.
• Incompatible change (renamed or retyped fields, a new required input): declare a new contract version, deploy a worker that implements it, then deploy the workflow version that uses it. Keep the worker for the old contract version running until no execution needs it.

An SDK worker registers each task name once, so serve two versions of the same contract from two worker processes with different worker ids. orbit workers list shows which name@version each worker serves.

Using ORBIT in CI

Three commands are useful in a pipeline. All of them work offline; none needs a running server.

orbit check --format json prints machine-readable diagnostics with codes, file, line and column, which you can turn into review annotations:

{
  "diagnostics": [
    {
      "severity": "error",
      "code": "E0405",
      "message": "value may be `null` but `String` is required",
      "location": { "file": "null.orbit", "line": 33, "column": 32 },
      "end_line": 33,
      "end_column": 53,
      "labels": [],
      "notes": [],
      "help": "provide a fallback with `coalesce(value, default)`, or declare the target as optional with `?`"
    }
  ]
}

A GitHub Actions job that installs the CLI with the install script and checks every source file:

name: orbit
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install orbit
        run: |
          curl -fsSL https://github.com/AjmalX0/Orbit/releases/latest/download/install.sh \
            | ORBIT_VERSION=v0.1.0 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: orbit check workflows/*.orbit
      - run: orbit fmt --check workflows/*.orbit contracts/*.orbit

Pin ORBIT_VERSION so that a new release does not change your pipeline unexpectedly.

To deploy from CI, compile once and deploy the IR artifacts. orbit validate checks compiled .json files, and orbit deploy accepts them as well as .orbit sources:

orbit compile workflows/*.orbit -o build
orbit validate build/*.json
ORBIT_SERVER=https://orbit.internal:7233 ORBIT_TOKEN="$ORBIT_ADMIN_TOKEN" orbit deploy build/*.json

compiled Bye@1.0.0 -> build/bye.orbit.json
compiled Hello@1.0.0 -> build/hello.orbit.json
ok build/bye.orbit.json is valid orbit-ir/1 (Bye@1.0.0, sha256:f8818e42acc5fa28a7e881b49abee1adc6febd65df6dd0d6c48b911b7ef97150)
ok build/hello.orbit.json is valid orbit-ir/1 (Hello@1.0.0, sha256:317903c71c7f843f965f75bde4e69cd36df4a05f16ee8a244236b31383902d65)
deployed Bye@1.0.0 (sha256:f8818e42acc5)
deployed Hello@1.0.0 (sha256:317903c71c7f)

Running orbit deploy again prints up to date for each definition that is already registered with the same content.

orbit deploy exits with status 1 on a DEFINITION_CONFLICT, which catches a workflow that changed without a version bump.

See also

• Files and imports
• Versioning
• Formatter
• CLI reference
• Compiler diagnostics

Files and imports

This page describes how ORBIT source is organized on disk: what a source file contains, how import combines files into one compilation, how names are shared between files, and how comments and whitespace work.

Source files

ORBIT source files are UTF-8 text files with the .orbit extension. A file contains any number of top-level declarations, in any order:

Declaration order does not matter. A workflow can use a schema or task that is declared further down the same file, or in a file that is imported later.

Test declarations are type-checked with the rest of the compilation, so orbit check reports their errors, but they never become part of the compiled output: orbit compile, orbit deploy and orbit run ignore them. A common convention is to keep a workflow’s tests in a separate <name>.test.orbit file that imports the workflow file.

Anything else at the top level is a syntax error, E0104:

workflow Example {
    version "1.0.0"
}

step orphan { sleep 1s }

error[E0104]: expected a declaration, found `step`
 --> example.orbit:5:1
  |
5 | step orphan { sleep 1s }
  | ^^^^
  = note: top-level declarations are `workflow`, `schema`, `task`, `import` and `test`

error: compilation failed: 1 error(s), 0 warning(s)

Imports

import takes a string literal with a path. The path is resolved relative to the directory of the file that contains the import, not relative to the current working directory.

// workflows/orders.orbit
import "../contracts/payments.orbit"
import "shared.orbit"            // workflows/shared.orbit

The compiler loads files as follows:

• Every file is loaded once, even if several files import it. Files are identified by their canonical path, so a/../b.orbit and b.orbit are the same file.

• Import cycles are allowed. If a.orbit imports b.orbit and b.orbit imports a.orbit, each file is still loaded once.

• An import that cannot be read is reported as E0206 at the import declaration:

  error[E0206]: cannot import `missing.orbit`: No such file or directory (os error 2)
   --> main.orbit:1:1
    |
  1 | import "missing.orbit"
    | ^^^^^^^^^^^^^^^^^^^^^^
  

There is no module system and no selective import: an import brings every declaration of the imported file, and of the files it imports, into the compilation.

One namespace

All files in a compilation share a single namespace for each kind of declaration:

• schema names,
• task names (strings such as "payments.charge"),
• workflow names.

Declaring the same schema, task or workflow twice, in the same file or in different files, is an error (E0200), with a label pointing at the first declaration. The three kinds have separate namespaces, so a schema and a workflow may share a name.

The built-in prelude is part of every compilation. It declares the task orbit.http.request (see HTTP adapter). Task names that start with orbit. are reserved for built-in tasks, and declaring one is E0200.

Compiling several files

orbit check, orbit compile and orbit deploy accept one or more files; orbit run and orbit graph take one file. The files you name, plus everything they import, form one compilation:

orbit check workflows/orders.orbit
orbit check contracts.orbit workflows/*.orbit

Workflows declared in imported files are compiled too. If main.orbit imports lib.orbit and both declare workflows, orbit check main.orbit reports both:

ok Lib@1.0.0 (0 steps)
ok Main@1.0.0 (1 steps)

A common layout keeps task contracts and shared schemas in one file that every workflow file imports. See Project layout.

Comments

ORBIT has two kinds of comments:

• Line comments start with // and run to the end of the line.
• Block comments start with /* and end with */. Block comments nest, so you can comment out a region that already contains a block comment.

/* Contracts for the payments service.
   /* Nested comments are allowed. */
*/
task "payments.authorize" {
    version "1.0.0"                       // the contract version
    input { order_id: String, amount: Float }
    output { authorization_id: String }
}

An unterminated block comment is E0003. Comments are kept by orbit fmt.

Whitespace, newlines and separators

Spaces, tabs and newlines are insignificant, with one exception: an infix operator must be on the same line as its left operand. This rule lets you write one field per line without commas. It is described in Expressions.

Commas and semicolons between members, fields and object entries are optional. These three declarations are equivalent:

schema Point { x: Int, y: Int }
schema Point2 { x: Int; y: Int }
schema Point3 {
    x: Int
    y: Int
}

List literals are the exception: items are separated by commas or by line breaks, and a semicolon is not accepted between list items.

Keywords are contextual

Apart from true, false and null, ORBIT has no reserved words. A word such as step, input, version or timeout acts as a keyword only where the grammar expects that keyword. Everywhere else it is an ordinary identifier, so it can be a field name or even a declaration name. See Grammar for the full list and the few names that are reserved in specific positions.

See also

• Project layout
• Schemas
• Task contracts
• Testing workflows
• Grammar
• Compiler diagnostics

Types

ORBIT is statically typed. The compiler checks every value that flows between the workflow input, task contracts, step outputs, child workflows and the workflow result before anything runs, and the runtime validates payloads again at every boundary. This page lists every type, its JSON encoding, how to write values of it, and the compatibility rules the type checker applies.

Primitive types

Details:

• Int. Integer literals that do not fit in 64 bits are E0006. Arithmetic that overflows at runtime is an expression error, not a wrap-around.
• Duration. A duration literal is a number followed by a unit: ms, s, m (minutes), h or d. Fractional values are allowed and rounded to the nearest millisecond (1.5s is 1500 ms). A bare number where a duration is required is E0101, and an unknown unit is E0005. Duration supports no operators: you cannot add or compare durations.
• Timestamp. The accepted form is YYYY-MM-DDTHH:MM:SS[.fraction](Z|±HH:MM). The T may also be t or a space, and Z may be z. A string literal checked against Timestamp is validated at compile time (E0400).
• UUID. 36 characters, hyphens at positions 9, 14, 19 and 24, hexadecimal digits in either case elsewhere. String literals checked against UUID are validated at compile time (E0400).
• Bytes. A string literal is a String, not Bytes, so passing "aGVsbG8=" where Bytes is required is E0400. Pass Bytes values through from the workflow input or a step output, or declare the field as String if you build the encoding yourself.
• String to UUID or Timestamp. Only literals are converted. A String value read from input or a step output is not accepted where UUID or Timestamp is required; declare the source field with the precise type.

Composite types

• Map keys must be String, because maps are JSON objects. Map<Int, String> is E0204.
• T?? is the same type as T?.
• Record types, named or anonymous, list fields with optional defaults. See Schemas.
• Type names are case-sensitive. An unknown type name is E0201, with a suggestion when a known type is close. List and Map without type arguments are E0201 too.

schema Shipment {
    id: UUID
    created_at: Timestamp
    packages: List<{ sku: String, weight_kg: Float }>
    labels: Map<String, String>
    note: String?
    raw: JSON
}

Optional types and null

T? means “a T, or null”. Three things produce optional values:

• fields declared T?,
• references to a step that has a when condition, because the step may be skipped (see Conditions),
• indexing a list or map, because the element may be missing.

The literal null has its own type, written null in diagnostics. It is accepted only where an optional type (or JSON) is expected.

A value of type T? is not accepted where T is required. The compiler reports E0405 and suggests coalesce:

task "users.notify" {
    input { name: String }
    output { ok: Bool }
}

workflow Notify {
    version "1.0.0"
    input { name: String? }
    step send { worker "users.notify" with { name: input.name } }
}

error[E0405]: value may be `null` but `String` is required
 --> notify.orbit:9:52
  |
9 |     step send { worker "users.notify" with { name: input.name } }
  |                                                    ^^^^^^^^^^
  = help: provide a fallback with `coalesce(value, default)`, or declare the target as optional with `?`

error: compilation failed: 1 error(s), 0 warning(s)

Fix it with a fallback, name: coalesce(input.name, "customer"), or make the contract field optional.

The JSON type

JSON is the dynamic type. Any value is accepted where JSON is expected, and a JSON value is accepted wherever any type is expected. Member access and indexing on JSON produce JSON, and operators that involve a JSON operand are not checked at compile time. The runtime still validates payloads against contracts, so a wrong value surfaces as INPUT_CONTRACT_VIOLATION or OUTPUT_CONTRACT_VIOLATION when the step runs.

JSON counts as optional: it may hold null.

Compatibility rules

The type checker asks one question everywhere: can a value of type S be used where type D is expected? The rules are:

A mismatch is E0400, with a note that names the field or element at fault when the types are nested.

Record width subtyping

Records are structural: the schema name does not matter, only the fields. A record with more fields than the target is accepted. A field the target declares as optional (T?) or with a default may be missing from the source. This lets you pass a whole step output or input record to a contract that only needs part of it:

task "crm.lookup" {
    input { customer: { id: String } }
    output { tier: String }
}

workflow Lookup {
    version "1.0.0"
    input { customer: { id: String, email: String, name: String } }
    step lookup { worker "crm.lookup" with { customer: input.customer } }
}

Object literals are exact

An object literal written directly where a record type is expected must not contain fields that the record does not declare. Extra fields there are almost always typos, so the compiler reports E0404 and suggests the closest field:

task "crm.lookup" {
    input { customer_id: String }
    output { tier: String }
}

workflow Lookup {
    version "1.0.0"
    input { id: String }
    step lookup { worker "crm.lookup" with { customer_id: input.id, cutomer_tier: "gold" } }
}

error[E0404]: unknown field `cutomer_tier` for `{ customer_id: String }`
 --> lookup.orbit:9:69
  |
9 |     step lookup { worker "crm.lookup" with { customer_id: input.id, cutomer_tier: "gold" } }
  |                                                                     ^^^^^^^^^^^^
  = help: did you mean `customer_id`?

error: compilation failed: 1 error(s), 0 warning(s)

Missing required fields in an object literal are E0403, which lists every missing field with its type.

Type inference

Expressions without an expected type are inferred:

When two types have to be combined (list items, if branches, coalesce arguments), the compiler uses the smallest type that both fit into: equal types stay the same, null with T gives T?, Int with Float gives Float, JSON with anything gives JSON, and of two compatible records the one with fewer fields wins. Other combinations are E0400.

A workflow without an output declaration takes the inferred type of its return expression as its output type. See Workflows.

Runtime validation

Values cross process boundaries as JSON, so the runtime validates them against the declared types:

A worker that returns null as its output is treated as returning {}. Validation of Float accepts any JSON number. Validation of Int requires an integer, and validation of Duration requires a non-negative integer.

See also

• Schemas
• Expressions
• Built-in functions
• Conditions
• Compiler diagnostics

Schemas

A schema is a named record type. You declare schemas for data that several contracts or workflows share, such as an order line or a payment request. This page covers the schema syntax, required and optional fields, default values, and the rules the compiler enforces on schema declarations.

Declaring a schema

schema LineItem {
    sku: String
    quantity: Int = 1          // default used when the field is absent
    note: String?              // optional: may be null or missing
}

A schema has a name (an identifier) and a list of fields. Each field has a name, a type, and optionally a default value after =. Fields can be separated by newlines, commas or semicolons.

Schemas can use any type, including other schemas and anonymous records:

schema Address {
    line1: String
    city: String
    country: String = "US"
}

schema Customer {
    id: String
    email: String
    shipping: Address
    billing: Address?
    preferences: { newsletter: Bool = false, language: String = "en" }
}

A schema is a type, so you use its name anywhere a type is expected: in task input and output, in workflow input and output fields, inside List<> and Map<String, >, and in other schemas.

Required, optional and defaulted fields

Every field is in one of three states:

A field can be both optional and defaulted (retries: Int? = 3), in which case the default is applied when the field is absent, and an explicit null is kept.

The runtime applies defaults, recursively through nested records, lists and maps, whenever it accepts a value of the type: execution input, task input after with is evaluated, and worker output. Workers therefore always see the defaulted fields, and a workflow can rely on a defaulted output field even if an older worker does not send it.

Default values

A default must be a constant expression of the field’s type. It may use literals, object and list literals, operators, if and the built-in functions, but not input, execution or step references. The compiler evaluates the default once and stores the result in the compiled IR.

schema RetryOptions {
    max_attempts: Int = 3
    window_ms: Int = 60 * 1000
    labels: Map<String, String> = { team: "payments" }
    tags: List<String> = []
    owner: String? = null
}

The compiler reports:

• a reference to input, execution or a step: E0401, for example error[E0401]: `input` cannot be used in a default value;
• a value of the wrong type: E0400; for example name: String = null is rejected because null is not a String (declare String? instead);
• an expression that fails when evaluated, such as 1 / 0: E0205.

Rules the compiler enforces

Errors in schemas that no workflow uses are still reported.

A recursive schema is rejected with the cycle:

schema Category {
    name: String
    parent: Category?
}

error[E0202]: recursive schema `Category`
 --> category.orbit:3:13
  |
3 |     parent: Category?
  |             ^^^^^^^^
  = note: cycle: Category -> Category
  = help: schemas must be finite; break the cycle with a `JSON` or `String` id field

error: compilation failed: 1 error(s), 0 warning(s)

Model the relationship with an identifier instead, for example parent_id: String?.

Schemas are structural

Schemas are compared by their fields, not by their names. Two schemas with the same fields are interchangeable, and a record with extra fields is accepted where a schema with fewer fields is expected (see record width subtyping). The schema name appears in diagnostics and in the compiled IR, where schemas are inlined.

Anonymous records

Wherever a type is expected, you can write a record type inline instead of naming it:

task "risk.score" {
    version "1.0.0"
    input { customer_id: String, amount: Float }
    output { score: Float, reasons: List<String> }
}

Inline records follow the same rules as schemas, including defaults and optional fields. Workflow input and output blocks are inline records too.

See also

• Types
• Task contracts
• Workflows
• Compiler diagnostics

Task contracts

A task contract declares a unit of work that workers implement: its name, its version, and the types of its input and output. Workflows call tasks by name, and the compiler checks every call against the contract. Workers in any language register against the same contract. This page covers the task declaration, how the compiler uses it, and how the runtime enforces it.

Declaring a task

schema PaymentRequest {
    order_id: String
    amount: Float
    currency: String = "USD"
}

task "payments.charge" {
    version "1.0.0"
    description "Charge a customer's card"
    input PaymentRequest                    // a schema...
    output { transaction_id: String }       // ...or an inline record
}

The name is a string literal. By convention it is a dotted, lowercase service.action name, but any string is allowed except names starting with orbit., which are reserved for built-in tasks.

Members

Members can appear in any order, each may be followed by an optional : (version: "1.0.0"), and separators between them are optional.

input and output must be record types: a schema name, an inline record, or JSON. Any other type is E0310:

task "math.square" {
    input Int
    output { value: Int }
}

error[E0310]: task input must be a record type, found `Int`
 --> square.orbit:2:11
  |
2 |     input Int
  |           ^^^

error: compilation failed: 1 error(s), 0 warning(s)

Wrap scalar values in a record (input { value: Int }). A task with no input takes no input, so a step can call it without with.

Rules the compiler enforces

Declaring how a task is undone

compensated_by records, on the contract, which task reverses its effect:

task "inventory.reserve" {
    version "1.0.0"
    input { order_id: String, quantity: Int }
    output { reservation_id: String }
    compensated_by "inventory.release"
}

task "inventory.release" {
    version "1.0.0"
    input { reservation_id: String }
    output { released: Bool }
}

workflow Reserve {
    version "1.0.0"
    input { order_id: String, quantity: Int }

    step reserve {
        worker "inventory.reserve"
        with { order_id: input.order_id, quantity: input.quantity }
        compensate {
            worker "inventory.release"
            with { reservation_id: reserve.reservation_id }
        }
    }
}

The contract author knows which tasks have effects that must be undone; the compiler then warns every workflow author who calls the task without the matching compensation. The runtime does not use compensated_by: a step is compensated only by its own compensate block. Like the rest of the contract, compensated_by is part of the definition hash of every workflow that uses the task. See Static safety checks.

How the compiler uses a contract

When a step runs a task with worker "payments.charge":

• The step’s with expression is checked against the contract input. Object literals must provide every required field (E0403) and must not contain unknown fields (E0404). See Types.
• A step without with is accepted only if the contract input has no required fields. Otherwise the compiler reports E0403 and lists the missing fields.
• The contract output is the type other expressions see when they reference the step, for example charge.transaction_id: String.

task "payments.charge" {
    version "1.0.0"
    input { order_id: String, amount: Float }
    output { transaction_id: String }
}

workflow Pay {
    version "1.0.0"
    input { order_id: String, amount: Float }

    step charge {
        worker "payments.charge"
        with { order_id: input.order_id, amount: input.amount }
    }

    return { transaction_id: charge.transaction_id }
}

The compiled IR embeds every contract a workflow uses, so the runtime does not need the source files.

How the runtime enforces a contract

The runtime validates the data on both sides of every task:

1. Input. When the step is scheduled, the runtime evaluates with, applies the contract’s input defaults, and validates the result. Unknown fields are allowed. An invalid value fails the step with the non-retryable error INPUT_CONTRACT_VIOLATION.
2. Output. When a worker reports success, the runtime applies the output defaults and validates the result. Unknown fields are allowed, so a worker can add fields without breaking older workflows. An invalid result fails the attempt with OUTPUT_CONTRACT_VIOLATION, which is not retried. A null result counts as {}.

Each task is routed to a worker that announced the same task name and the same contract version. A step’s using <language> narrows that further to workers whose runtime matches (case-insensitively); using any matches every worker. See How workers work.

Changing a contract

A contract is part of every workflow definition that uses it, and it contributes to the workflow’s definition hash. Changing a contract, even only its output, changes the hash of every workflow that uses it, so you must bump those workflows’ versions before you register them again. Bump the contract version when the change is incompatible for workers, so that old workers stop receiving the task. See Versioning.

Built-in tasks

Built-in tasks run inside the runtime instead of on a worker. There is one, orbit.http.request, declared in the prelude that every compilation includes:

workflow Ping {
    version "1.0.0"
    step probe {
        worker "orbit.http.request"
        with { url: "https://status.example.com/health" }
    }
    return { status: probe.status }
}

See HTTP adapter.

See also

• Schemas
• Steps
• Compensation
• Static safety checks
• Versioning
• How workers work
• Worker protocol

Workflows

A workflow declares what should happen, in which order, and with which guarantees: its typed input, the steps that do the work, and the result it returns. The compiler turns each workflow into an immutable, versioned definition that the runtime executes durably. This page covers the workflow declaration and each of its members.

Declaring a workflow

workflow OrderProcessing {
    version "1.0.0"
    description "Validate, charge and confirm one order"
    timeout 5m

    input {
        order_id: String
        customer_id: String
        amount: Float
        currency: String = "USD"
        items: List<LineItem>
    }

    output {
        status: String
        transaction_id: String
    }

    step validate {
        worker "orders.validate"
        with { order_id: input.order_id, amount: input.amount, items: input.items }
    }

    step charge {
        worker "payments.charge"
        after validate
        with { order_id: input.order_id, amount: input.amount, currency: input.currency }
    }

    return { status: "completed", transaction_id: charge.transaction_id }
}

The workflow name is an identifier. It is unique in the compilation (E0200) and is what you pass to orbit run and to the start API.

Members

Members can appear in any order. version, description and timeout accept an optional : after the keyword. input, output and signal name are followed directly by a record body. A workflow can declare any number of steps, signals and queries; step, signal and query names are separate namespaces, each unique within the workflow (E0302, E0317, E0318).

A workflow has at most one on block of each kind, and one on event block per signal (E0319); any other kind, such as on success, is rejected with E0105. Handler blocks contain only step declarations. Use compensation to undo work, and outcome handlers for what should happen after it, such as notifying a customer.

Version

Every workflow declares a version. A version that is not MAJOR.MINOR.PATCH (optionally with a -pre or +build suffix) produces warning W0201. A missing version is an error:

workflow Nightly {
    step pause { sleep 1h }
}

error[E0500]: workflow `Nightly` has no version
 --> nightly.orbit:1:10
  |
1 | workflow Nightly {
  |          ^^^^^^^
  = help: add `version "1.0.0"`; running executions stay pinned to the version they started with

error: compilation failed: 1 error(s), 0 warning(s)

See Versioning for how versions and definition hashes interact.

Input

input declares the fields an execution starts with, using the same field syntax as a schema. Expressions read them as input.<field>.

When an execution starts, the runtime:

1. treats a missing or null input as {},
2. applies the declared defaults, recursively,
3. validates the result strictly: missing required fields, values of the wrong type and fields the workflow does not declare are rejected.

A rejected input fails the start request with INVALID_INPUT, and no execution is created:

orbit run order.orbit --input '{"order_id": "A-1", "amount": "12"}'

error: INVALID_INPUT (400): workflow input is invalid at $.amount: expected Float, found a string

Child workflows started by a workflow step get their defaults applied too, but their input is validated leniently, because the parent’s with expression was already type-checked against the child’s input.

Output and return

return maps step results to the workflow result. It is evaluated once, after every step has finished (succeeded or been skipped), and it can read input, execution and every step.

• With output and return, the return expression is checked against output, with the same rules as a task input: object literals must be exact (E0404) and complete (E0403).
• With output but no return, the result is {}, which is accepted only if output has no required fields. Otherwise the compiler reports E0501.
• With return but no output, the output type is the inferred type of the return expression.
• With neither, the result is {}.

workflow Quote {
    version "1.0.0"
    input { order_id: String, items: Int }

    step quote {
        worker "shipping.quote"
        with { order_id: input.order_id, items: input.items }
    }

    // No `output` block: the output type is inferred as
    // { carrier: String, cost: Float, expensive: Bool }.
    return { carrier: quote.carrier, cost: quote.cost, expensive: quote.cost > 50.0 }
}

The runtime validates the result against the output type before it completes the execution. A failure there, or an expression error while evaluating return, fails the workflow with OUTPUT_CONTRACT_VIOLATION or EXPRESSION_ERROR. No compensation runs in that case, because every step succeeded.

Timeout

The workflow timeout is a deadline for the whole execution, counted from the moment the execution was created. When it passes, the runtime:

1. withdraws steps that have not started,
2. waits for attempts that are in flight,
3. runs the compensations of the steps that succeeded,
4. ends the execution as TIMED_OUT.

Step timeouts, retries, sleeps and waits for signals all count against the workflow deadline. A workflow timeout also bounds every await step that has no timeout of its own (otherwise the compiler reports W0606). Compensations run after the deadline and are not limited by it. See Retries and timeouts.

Signals and queries

A workflow can declare the signals it accepts and the queries it answers:

workflow Approval {
    version "1.0.0"
    timeout 14d
    input { request_id: String }

    signal review { approved: Bool, reviewer: String }

    step decision { await review }

    query status = { decided: !is_null(decision), approved: decision.approved }

    return { approved: decision.approved }
}

orbit signal <id> review --data '{...}' sends a validated payload, which the decision step receives as its output. orbit query <id> status evaluates the query against the current state; in a query every step output is optional, because the step may not have run yet. A workflow that declares a signal or a query compiles to orbit-ir/2. See Signals and queries.

Execution lifecycle

An execution is RUNNING until it completes, or until it is aborted by a step failure, a cancellation or the workflow timeout:

RUNNING ──► COMPLETED
   │
   └──► COMPENSATING ──► FAILED | CANCELLED | TIMED_OUT

A failed, cancelled or timed-out execution records a compensation outcome: none (nothing to compensate), completed or failed. See Compensation and Executions and history.

Execution metadata

Expressions can read three fields of the running execution:

These are often used to build idempotency keys or correlation ids:

workflow Welcome {
    version "1.0.0"
    input { email: String }
    step send {
        worker "emails.send"
        with { to: input.email, template: "welcome" }
        idempotency_key: "welcome-" + execution.id
    }
}

See also

• Steps
• Signals and queries
• Schemas
• Versioning
• Executions and history
• Compensation
• Outcome handlers

Steps

A step is one unit of work in a workflow: a task run by a worker, a child workflow, a durable timer, a wait for a signal, or a value computed by the runtime. Each step declares what it does, what it needs, and the policies that apply to it. This page is the reference for the step block: its actions, every member, where each member is allowed, and the type other expressions see when they reference the step.

Anatomy of a step

step process_payment {
    worker "payments.charge"          // the action: a task contract
    using python                      // only route to Python workers
    after reserve_inventory           // explicit ordering
    when analyze_risk.score < 0.8     // run only if true, otherwise skip
    with {                            // the task input, checked against the contract
        order_id: input.order_id
        amount: input.amount
        currency: input.currency
    }
    idempotency_key: "charge-" + input.order_id
    timeout 30s                       // per attempt
    queue_timeout 2m                  // fail if no worker picks it up in time
    retry {
        attempts: 5                   // total attempts, including the first
        backoff: exponential
        initial_delay: 500ms
        max_delay: 10s
        non_retryable: ["CARD_DECLINED"]
    }
    compensate {
        worker "payments.refund"
        with { transaction_id: process_payment.transaction_id, amount: input.amount }
    }
}

The step name is an identifier. It is unique within the workflow (E0302), and expressions use it to read the step’s output (process_payment.transaction_id). Members can appear in any order, and separators between them are optional.

Actions

Every step has exactly one action:

A step without an action is E0301. A step with two actions is E0106:

task "reports.build" {
    output { url: String }
}

workflow Report {
    version "1.0.0"
    step build {
        worker "reports.build"
        sleep 10s
    }
}

error[E0106]: a step can only have one `worker`, `workflow`, `sleep`, `await` or `compute`
 --> report.orbit:9:9
  |
9 |         sleep 10s
  |         ^^^^^
  = help: split the work into separate steps

error: compilation failed: 1 error(s), 0 warning(s)

Members

Syntax notes:

• Every member except retry, compensate and for accepts an optional : after the keyword: timeout: 30s is the same as timeout 30s. retry and compensate are followed directly by {, and retry: { is a syntax error.

• DURATION is a duration literal such as 30s. Expressions are not accepted where a duration is required.

• after takes a comma-separated list of step names. You can repeat after; the lists are combined.

• Every other member may appear at most once per step (E0106).

• An unknown member is E0102, with a suggestion for close misspellings:

  task "reports.build" {
      output { url: String }
  }
  
  workflow Report {
      version "1.0.0"
      step build {
          wroker "reports.build"
      }
  }
  

  error[E0301]: step `build` does nothing
   --> report.orbit:7:10
    |
  7 |     step build {
    |          ^^^^^
    = help: add `worker "task.name"`, `workflow "Name"`, `sleep 10s`, `await <signal>` or `compute <expression>`
  
  error[E0102]: unexpected `wroker` in step
   --> report.orbit:8:9
    |
  8 |         wroker "reports.build"
    |         ^^^^^^
    = help: did you mean `worker`?
  
  error: compilation failed: 2 error(s), 0 warning(s)
  

Where members are allowed

Not every member makes sense for every kind of step. The compiler rejects misplaced members with E0307 (or E0308 for compensation):

A compensate block must call a task with worker; sleep, workflow, await or compute there is E0308.

Step names

Step names are identifiers. Some names are reserved because expressions use them for other purposes, and declaring a step with one of them is E0306:

input, execution, output, if, then, else

Input: with

with is an expression whose value becomes the task input (or the child workflow input). It is usually an object literal, but any expression of a compatible type works:

schema PaymentRequest {
    order_id: String
    amount: Float
    currency: String
}

task "payments.authorize" {
    input PaymentRequest
    output { authorization_id: String }
}

workflow Authorize {
    version "1.0.0"
    input { payment: PaymentRequest, note: String? }

    // Pass a whole record from the input.
    step authorize { worker "payments.authorize" with input.payment }
}

The expression is checked against the contract input (see Types). It is evaluated once, when the step is scheduled, and the result is stored in the execution history. Retries and redeliveries reuse the stored value. If evaluation fails at runtime, for example because of a division by zero, the step fails with the non-retryable error EXPRESSION_ERROR.

A step without with passes {}. That is accepted only when the contract input has no required fields; otherwise the compiler reports E0403.

Reading another step’s output in with makes this step depend on that step. See Dependencies.

Routing: using

using restricts which workers receive the task: only workers that announce the given runtime are eligible. The value is an identifier, compared case-insensitively with the runtime a worker announces. using any places no restriction.

The compiler knows these runtime names: python, typescript, javascript, go, rust, java, kotlin, csharp, ruby, php, elixir, swift, cpp, http and any. Any other name produces warning W0301, with a suggestion when the name is close to a known one:

task "risk.analyze" {
    input { customer_id: String }
    output { score: Float }
}

workflow Risk {
    version "1.0.0"
    input { customer_id: String }
    step score {
        worker "risk.analyze"
        using pyhton
        with { customer_id: input.customer_id }
    }
}

warning[W0301]: unknown worker language `pyhton`
  --> risk.orbit:11:15
   |
11 |         using pyhton
   |               ^^^^^^
   = help: did you mean `python`?

The warning does not stop compilation, but a misspelled runtime means no worker ever receives the task.

Step output types

Expressions refer to a step by name. The type they see depends on the step’s action and on when and for:

Inside the step’s own compensate block, the step’s output is never optional, and for a for step it is the output of the element being compensated. See Compensation.

Units and status

At runtime each step is one or more units. A plain step is one unit, keyed by its name. A for step has one unit per element, keyed name[0], name[1], and so on. A compensation is a unit keyed compensate:<unit>, and a step of an outcome handler is keyed on_<kind>:<step>. Unit keys appear in orbit status, orbit logs, idempotency keys and child execution ids.

A unit moves through these states:

See Executions and history for the events behind these transitions.

See also

• Dependencies
• Conditions
• Retries and timeouts
• Fan-out
• Compensation
• Signals and queries
• Compute steps
• Compiler diagnostics

Dependencies

Steps in a workflow form a directed acyclic graph. The compiler builds the graph from explicit after lists and from the data each step reads, rejects cycles, and fixes a deterministic order. The runtime starts a step as soon as everything it depends on has finished, and runs independent steps concurrently. This page explains how dependencies are formed and checked.

Explicit dependencies: after

after lists steps that must finish before this step starts:

step notify {
    worker "notifications.send"
    after validate_order, reserve_inventory
    with { customer_id: input.customer_id, message: "Order received" }
}

Use after when there is an ordering requirement that the data does not express, for example “send the confirmation only after the inventory is reserved”. You can repeat after in a step; the lists are combined.

Implicit dependencies: data references

Reading a step’s output makes the reading step depend on it. You do not need to repeat that dependency in after. References count in these members:

In this workflow, charge depends on risk because its when reads risk.score, and on reserve through after:

workflow Checkout {
    version "1.0.0"
    input { order_id: String, customer_id: String, amount: Float, items: List<LineItem> }

    step risk {
        worker "risk.analyze"
        with { customer_id: input.customer_id, amount: input.amount }
    }

    step reserve {
        worker "inventory.reserve"
        with { order_id: input.order_id, items: input.items }
    }

    step charge {
        worker "payments.charge"
        after reserve
        when risk.score < 0.8
        with { order_id: input.order_id, amount: input.amount, currency: "USD" }
    }

    return { reservation_id: reserve.reservation_id, transaction_id: charge.transaction_id }
}

risk and reserve have no dependency on each other, so they run at the same time. charge starts when both have finished.

When a step becomes eligible

A step is scheduled when all of these hold:

1. every direct dependency has finished as SUCCEEDED or SKIPPED,
2. the workflow is not being aborted (no step has failed permanently, and the execution has not been cancelled or timed out),
3. its when condition, if any, is true.

A skipped dependency counts as finished. Its output is null, which is why references to a conditional step are optional. See Conditions.

A failed dependency never lets a step start: the failure aborts the workflow, and pending steps are withdrawn (CANCELLED). See Compensation.

Concurrency

There is no implicit sequencing by source order. Steps without a path between them in the graph run concurrently, limited only by available workers. To run steps one after another, connect them with after or a data reference.

Rules the compiler enforces

An unknown after target suggests the closest step name:

task "shipping.quote" {
    input { order_id: String }
    output { carrier: String }
}

task "shipping.book" {
    input { order_id: String, carrier: String }
    output { tracking: String }
}

workflow Ship {
    version "1.0.0"
    input { order_id: String }
    step quote { worker "shipping.quote" with { order_id: input.order_id } }
    step book {
        worker "shipping.book"
        after qoute
        with { order_id: input.order_id, carrier: quote.carrier }
    }
}

error[E0303]: `after` references unknown step `qoute`
  --> ship.orbit:17:15
   |
17 |         after qoute
   |               ^^^^^
   = help: did you mean `quote`?

error: compilation failed: 1 error(s), 0 warning(s)

A cycle is reported with the full path and a label at each edge:

task "a.run" {
    input { n: Int }
    output { v: Int }
}

workflow Loop {
    version "1.0.0"
    step first { worker "a.run" with { n: second.v } }
    step second { worker "a.run" with { n: first.v } }
}

error[E0304]: circular dependency between steps
 --> loop.orbit:8:10
  |
8 |     step first { worker "a.run" with { n: second.v } }
  |          ^^^^^
  |                                           ------ `first` depends on `second`
9 |     step second { worker "a.run" with { n: first.v } }
  |                                            ----- `second` depends on `first`
  = note: cycle: first -> second -> first
  = help: the step graph must be acyclic; remove one of these dependencies

error: compilation failed: 1 error(s), 0 warning(s)

Reading a step’s own output, for example to “increment” a value, is E0305. Use two steps, or a compensation, which may read its own step.

Deterministic order

The compiler sorts steps topologically and breaks ties by source order. The resulting order is stored in the compiled IR, together with each step’s sorted dependency list, and the runtime evaluates steps in that order. The order, and therefore every scheduling decision, is the same on every replay.

To see the graph, run orbit graph, which renders Mermaid or Graphviz. See Workflow graphs.

See also

• Steps
• Conditions
• Workflow graphs
• Executions and history

Conditions

A when condition makes a step conditional: the step runs only if the condition is true, and is skipped otherwise. Because a skipped step produces no output, the type checker treats every reference to a conditional step as optional and makes you handle the missing value. This page covers the when member, skipped steps, and the patterns for working with optional results.

The when member

step manual_review {
    worker "notifications.send"
    when analyze_risk.score >= 0.8
    with { customer_id: input.customer_id, message: "Your order is under review" }
}

The condition is an expression of type Bool or Bool?. Any other type is E0408:

error[E0408]: `when` condition must be `Bool`, found `Int`

Like any data reference, a step read in when becomes a dependency (see Dependencies). when is allowed on task steps, workflow steps and sleep steps, but not inside a compensate block (E0307).

Evaluation

The runtime evaluates the condition once, when every dependency of the step has finished:

A skipped step has status SKIPPED, records a StepSkipped event, and has the output null. It is never compensated, because it did nothing.

Skipped steps and optional outputs

Because the step may be skipped, every reference to it is optional. If the task’s output is { transaction_id: String }, then:

Member access propagates null, so process_payment.transaction_id is null when the step was skipped, rather than an error.

Steps that depend on a skipped step still run. The type checker makes sure they handle the missing value: using an optional value where a non-optional one is required is E0405.

task "payments.charge" {
    input { order_id: String, amount: Float }
    output { transaction_id: String }
}

task "receipts.send" {
    input { order_id: String, transaction_id: String }
    output { sent: Bool }
}

workflow Pay {
    version "1.0.0"
    input { order_id: String, amount: Float }

    step charge {
        worker "payments.charge"
        when input.amount > 0.0
        with { order_id: input.order_id, amount: input.amount }
    }

    step receipt {
        worker "receipts.send"
        with { order_id: input.order_id, transaction_id: charge.transaction_id }
    }
}

error[E0405]: value may be `null` but `String` is required
  --> pay.orbit:23:58
   |
23 |         with { order_id: input.order_id, transaction_id: charge.transaction_id }
   |                                                          ^^^^^^^^^^^^^^^^^^^^^
   = help: provide a fallback with `coalesce(value, default)`, or declare the target as optional with `?`

error: compilation failed: 1 error(s), 0 warning(s)

Handling optional results

Choose one of these patterns, depending on what the downstream step should do when the conditional step was skipped.

Provide a fallback with coalesce:

step receipt {
    worker "receipts.send"
    with { order_id: input.order_id, transaction_id: coalesce(charge.transaction_id, "none") }
}

Skip the downstream step too, with its own condition:

step receipt {
    worker "receipts.send"
    when !is_null(charge)
    with { order_id: input.order_id, transaction_id: coalesce(charge.transaction_id, "") }
}

The condition does not narrow the type, so the with expression still needs coalesce.

Branch with if ... then ... else, or compare against null:

return {
    status: if charge.transaction_id == null then "not_charged" else "charged"
    transaction_id: charge.transaction_id
}

Declare the target as optional. If a contract field or a workflow output field is T?, an optional value can be passed to it directly.

Steps that share a condition

A step that can only run when a conditional step ran reads that step’s output as non-optional. The compiler recognizes two cases in the reading step’s when, which it splits at &&:

• a conjunct !is_null(step), or
• every conjunct of the other step’s own when, written in any order and with any spacing (conditions are compared by structure, not by text).

task "payments.charge" {
    input { order_id: String, amount: Float }
    output { transaction_id: String }
}

task "receipts.send" {
    input { order_id: String, transaction_id: String }
    output { sent: Bool }
}

workflow Pay {
    version "1.0.0"
    input { order_id: String, amount: Float, email_receipt: Bool }

    step charge {
        worker "payments.charge"
        when input.amount > 0.0
        with { order_id: input.order_id, amount: input.amount }
    }

    // Shares `input.amount > 0.0`: `charge` has run, so no `coalesce`.
    step receipt {
        worker "receipts.send"
        when input.amount > 0.0 && input.email_receipt
        with { order_id: input.order_id, transaction_id: charge.transaction_id }
    }
}

This is sound because a condition can only read values that were final before the step it guards was decided: input, execution and the step’s dependencies, which never change afterwards. When receipt runs, the same expression that made charge run is true again, and charge succeeded (had it failed, the execution would have stopped).

The rule applies to the step’s with, compute, idempotency_key, for list and compensate block. It does not apply to the when condition itself, which still reads conditional steps as optional, or to queries and return, which can be evaluated when the step has not run. A condition joined with ||, or one that differs in any other way, does not narrow; the step’s own output stays optional either way because it has a when.

Conditions and fan-out

On a for step, when decides once whether the whole step runs, before the list is expanded. The loop variable is therefore not in scope in when:

task "inventory.reserve" {
    input { sku: String }
    output { reservation_id: String }
}

workflow Reserve {
    version "1.0.0"
    input { skus: List<String> }
    step reserve {
        for sku in input.skus
        when sku != ""
        worker "inventory.reserve"
        with { sku: sku }
    }
}

error[E0401]: loop variable `sku` is not in scope in `when`
  --> reserve.orbit:11:14
   |
11 |         when sku != ""
   |              ^^^^^^^^^
   = note: `when` decides once whether the whole `for` step runs, before it fans out
   = help: to process only some elements, filter the list in a previous step

error: compilation failed: 1 error(s), 0 warning(s)

A skipped for step has the output null, so its type is List<T>?. for has no per-element filter clause; to process only some elements, iterate over filter(list, x => ...). See Fan-out.

Conditions and compensation

Inside a step’s own compensate block, the step’s output is not optional: a compensation only runs for a step that succeeded. See Compensation.

Constant conditions

A condition that reads nothing (no input, step output, execution field or variable) has the same value in every execution. The compiler evaluates it and warns: W0603 when it is false or null (the step never runs) and W0604 when it is true (the when only makes the output optional). See Static safety checks.

See also

• Expressions
• Static safety checks
• Built-in functions
• Types
• Dependencies
• Fan-out

Retries and timeouts

Retries and timeouts bound how long a step may take and how often the runtime tries it again. A retry block sets the policy for one step, timeout and queue_timeout limit each attempt, and the workflow timeout limits the whole execution. This page lists every setting with its default, and describes exactly when the runtime retries.

Retry policy

step charge {
    worker "payments.charge"
    with { order_id: input.order_id, amount: input.amount, currency: input.currency }
    retry {
        attempts: 5
        backoff: exponential
        initial_delay: 500ms
        max_delay: 10s
        non_retryable: ["CARD_DECLINED", "INSUFFICIENT_FUNDS"]
    }
}

retry is followed directly by { (no :). Inside, each setting is name: value, separated by commas, semicolons or newlines.

A step without a retry block makes one attempt. A retry block that omits a setting uses that setting’s default, so retry { attempts: 3 } retries twice with a fixed 1 second delay.

Every value must be a literal: expressions such as attempts: input.n are rejected. The compiler reports every problem with a retry block as E0410:

Backoff

The delay before attempt n (attempt 2 is the first retry) is:

For attempts: 6, backoff: exponential, initial_delay: 500ms, max_delay: 4s:

The delay is a durable timer: a retry that is waiting survives a runtime restart, and the attempt starts when the timer fires.

When the runtime retries

After an attempt fails, the runtime schedules another attempt only if all of these hold:

1. the error is retryable,
2. the error code is not listed in non_retryable (codes are compared exactly, including case),
3. attempts remain (attempt < attempts),
4. the workflow is not being aborted.

Otherwise the step fails permanently. If the policy allowed more than one attempt and they were all used, the error message ends with (gave up after N attempts).

Whether an error is retryable is decided by whoever reports it. Workers report errors with a code and a retryable flag (see How workers work). Errors that the runtime generates have a fixed classification:

Every retry reuses the input and idempotency key that were evaluated when the step was first scheduled. Redelivery after a lost worker is not a retry and does not use up an attempt; see Delivery guarantees.

Step timeout

timeout limits a single attempt, measured from the moment the task is dispatched to a worker until its result arrives:

step analyze {
    worker "risk.analyze"
    with { customer_id: input.customer_id, amount: input.amount }
    timeout 10s
    retry { attempts: 3, backoff: exponential, initial_delay: 1s }
}

Timeouts are cooperative. The worker is told to stop, through the cancellation list it receives with heartbeat responses, but the runtime cannot force an external operation to stop. If the timed-out attempt later reports success while the step is still unresolved, the runtime accepts that result, because the work did happen.

On a workflow step, timeout limits how long the parent waits for the child. When it expires, the step fails with TIMEOUT (workflow steps cannot retry) and the child execution is cancelled.

On an await step, timeout limits how long the step waits for its signal, from the moment it starts waiting. When it expires, the step fails with SIGNAL_TIMEOUT, which is never retried. See Signals and queries.

Queue timeout

queue_timeout limits how long an attempt may wait for a worker to pick it up:

step charge {
    worker "payments.charge"
    with { order_id: input.order_id, amount: input.amount, currency: input.currency }
    queue_timeout 2m
}

Use queue_timeout to fail fast when no worker for a task (or for the using runtime) is running, instead of waiting until the workflow deadline.

Workflow timeout

The workflow-level timeout limits the whole execution, measured from its creation, across all steps, retries, sleeps and waits for signals. When it passes, the runtime stops scheduling work, waits for in-flight attempts, runs compensations, and ends the execution as TIMED_OUT. See Workflows.

Where each setting is allowed

await steps accept timeout only, and compute steps accept none of the three (E0307): a compute step is evaluated by the runtime and cannot time out or be retried.

A child workflow is durable on its own. Put retries on the child’s steps.

Retries in the history

Each attempt appears in the execution history. A step with retry { attempts: 3, backoff: exponential, initial_delay: 100ms } that fails every time produces events like these (orbit logs <id>):

+   106ms   #9  StepScheduled             step=broken attempt=1
+   201ms  #10  StepDispatched            step=broken attempt=1 worker_id=orbit-runtime
+   203ms  #11  StepAttemptFailed         step=broken attempt=1 error=HTTP_ERROR request failed: io: Connection refused (os error 111)
+   205ms  #12  RetryScheduled            step=broken delay_ms=100
+   401ms  #13  StepScheduled             step=broken attempt=2
+   403ms  #14  StepDispatched            step=broken attempt=2 worker_id=orbit-runtime
+   406ms  #15  StepAttemptFailed         step=broken attempt=2 error=HTTP_ERROR request failed: io: Connection refused (os error 111)
+   407ms  #16  RetryScheduled            step=broken delay_ms=200
+   701ms  #17  StepScheduled             step=broken attempt=3
+   702ms  #18  StepDispatched            step=broken attempt=3 worker_id=orbit-runtime
+   704ms  #19  StepAttemptFailed         step=broken attempt=3 error=HTTP_ERROR request failed: io: Connection refused (os error 111)
+   705ms  #20  StepFailed                step=broken error=HTTP_ERROR request failed: io: Connection refused (os error 111) (gave up after 3 attempts)

See also

• Steps
• Idempotency
• Delivery guarantees
• Executions and history
• How workers work

Idempotency

ORBIT delivers every task at least once. A worker can receive the same task more than once, for example after a network failure hid its result or after a runtime restart, so workers must make their side effects idempotent. Every task carries an idempotency key for that purpose. This page explains the default key, how to set your own with idempotency_key, and how keys behave across retries, fan-out and compensation.

The default key

If a step does not set idempotency_key, its key is:

<execution id>/<unit key>

The default key is unique per execution and unit, and stable across retries and redeliveries.

Setting a key

idempotency_key takes an expression of type String:

step process_payment {
    worker "payments.charge"
    with { order_id: input.order_id, amount: input.amount, currency: input.currency }
    idempotency_key: "charge-" + input.order_id
}

Set your own key when the deduplication should span executions. In the example above, starting the workflow twice for the same order still charges the card once, provided the payment worker (or the payment provider) honors the key.

Rules:

• The expression must be a String. Another type is E0400, and a String? is E0405. Convert numbers with string.
• The expression can read input, execution, other steps (which become dependencies) and, in a for step or its compensation, the loop variable.
• It is evaluated once, when the unit is first scheduled, and stored in the history. Retries and redeliveries reuse it unchanged.
• If it evaluates to null at runtime (possible only through a JSON value), the default key is used.
• An evaluation error fails the step with EXPRESSION_ERROR.
• idempotency_key is allowed on task steps and in compensate blocks. It is not allowed on workflow steps or sleep steps (E0307).

Keys in fan-out steps

In a for step the key expression is evaluated separately for each element, with the loop variable bound. Include something that identifies the element, otherwise every element gets the same key and a worker that deduplicates by key would run only one of them:

step reserve {
    for item in input.items
    worker "inventory.reserve"
    with { order_id: input.order_id, items: [item] }
    idempotency_key: input.order_id + "/" + item.sku
}

If you omit idempotency_key, the default key already includes the element index (<execution id>/reserve[0], <execution id>/reserve[1], …).

Keys in compensations

A compensation has its own key, <execution id>/compensate:<unit> by default. You can set a business key in the compensate block, and it may read the compensated step’s output:

step process_payment {
    worker "payments.charge"
    with { order_id: input.order_id, amount: input.amount, currency: input.currency }
    idempotency_key: "charge-" + input.order_id
    compensate {
        worker "payments.refund"
        with { transaction_id: process_payment.transaction_id, amount: input.amount }
        idempotency_key: "refund-" + process_payment.transaction_id
    }
}

Child workflows

Workflow steps do not take an idempotency key. The child execution has a deterministic id, <parent id>.<step> (or <parent id>.<step>.<i> for an element of a for step), so the runtime never starts the same child twice. See Child workflows.

Starting executions idempotently

The same idea applies to starting executions. If you pass a client-chosen execution id (orbit run --id, or execution_id in the start API), starting twice with the same id returns the existing execution instead of creating a new one. Combined with the default keys, which contain the execution id, this makes a retried start safe end to end. See Executions and history.

What workers should do with the key

A worker receives the key with every task. Typical uses:

• pass it to an external API that supports idempotency keys,
• record it with the side effect in the same database transaction, and return the recorded result when the key is seen again,
• use it as a natural primary key for the record the task creates.

ORBIT does not promise exactly-once execution of external side effects. It promises that the key is stable, and that uncertain outcomes are redelivered with the same key rather than assumed to have failed. See Delivery guarantees.

See also

• Delivery guarantees
• Retries and timeouts
• Fan-out
• Compensation
• How workers work

Durable sleep

A sleep step waits for a fixed amount of time. The timer is kept by the runtime in the execution history, so it survives runtime restarts and needs no worker. This page covers the sleep action, the members it accepts, and how timers behave when a workflow is aborted.

Declaring a sleep step

workflow FollowUp {
    version "1.0.0"
    input { email: String }

    step welcome {
        worker "emails.send"
        with { to: input.email, template: "welcome" }
    }

    step cool_off {
        sleep 24h
        after welcome
    }

    step follow_up {
        worker "emails.send"
        after cool_off
        with { to: input.email, template: "follow-up" }
    }
}

The duration is a duration literal: a number followed by ms, s, m, h or d, for example 500ms, 1.5h or 7d. It cannot be an expression, so the wait time is fixed per workflow version. A bare number is E0101.

Behavior

sleep 0s is accepted and completes on the next tick.

Allowed members

A sleep step accepts only after and when:

workflow Wait {
    version "1.0.0"
    step pause {
        sleep 10m
        retry { attempts: 3 }
    }
}

error[E0307]: `retry` is not allowed in a `sleep` step
 --> wait.orbit:5:9
  |
5 |         retry { attempts: 3 }
  |         ^^^^^^^^^^^^^^^^^^^^^

error: compilation failed: 1 error(s), 0 warning(s)

Waiting until a point in time

ORBIT has no “sleep until” form, and expressions cannot read the clock, so a sleep duration cannot be computed from a timestamp. To run work at a specific time, start the execution at that time from an external scheduler.

See also

• Steps
• Dependencies
• Retries and timeouts
• Executions and history

Fan-out

A for step runs once per element of a list, as independent units that run in parallel up to an optional limit. Each element has its own retries, timeouts, idempotency key and compensation, and the step’s output is the list of element outputs in input order. This page covers the for member, max_parallel, typing, failure behavior and compensation of fan-out steps.

Declaring a fan-out step

workflow ReserveAll {
    version "1.0.0"
    input { order_id: String, items: List<LineItem> }

    step reserve {
        for item in input.items
        max_parallel 4
        worker "inventory.reserve"
        with { order_id: input.order_id, items: [item] }
        compensate {
            worker "inventory.release"
            with { reservation_id: reserve.reservation_id }   // this element's output
        }
    }

    return { reservations: reserve }
}

for <name> in <expression> binds a loop variable to each element. It has no optional :. The other step members (worker or workflow, with, retry, timeout, …) describe what happens for one element.

The list expression

The expression after in must be a list:

The list can come from the input, a previous step (which becomes a dependency), or a literal. It is evaluated once, when the step becomes eligible, and the evaluated list is stored in the history (StepFanOut). The number and content of the elements are therefore fixed, even across restarts.

The loop variable

The loop variable is in scope in with, idempotency_key and compensate. It is not in scope in when, which decides once whether the whole step runs (E0401). See Conditions.

The variable name cannot be the name of a step in the workflow, or input or execution (E0413):

error[E0413]: loop variable `input` shadows a built-in name

Concurrency: max_parallel

max_parallel N caps how many elements are in progress at once: scheduled, running, waiting for a retry, or waiting for redelivery. When an element finishes, the next pending element (in list order) starts.

Units and keys

Each element is its own unit, keyed <step>[<index>] with a zero-based index: reserve[0], reserve[1], and so on. Each unit has:

• its own input, evaluated with the loop variable bound to that element,
• its own attempts and retry delays, following the step’s retry policy,
• its own timeout and queue_timeout,
• its own idempotency key, <execution id>/reserve[<index>] by default (see Idempotency),
• for a workflow step, its own child execution, <parent id>.reserve.<index>.

orbit status lists the element units under the step.

Output

The step succeeds when every element succeeds. Its output is the list of the element outputs, in the order of the input list, regardless of the order in which elements finished.

You can index the result like any list. Indexing is optional-typed, because the index may be out of range:

return {
    count: len(reserve)
    first_reservation: reserve[0].reservation_id     // String?
}

An empty list succeeds immediately with the output [], without contacting any worker.

Failure

When an element fails permanently, after its own retries:

1. the step fails with that element’s error,
2. the workflow is aborted: elements that have not started are withdrawn, elements in flight are awaited,
3. compensation runs for every element that succeeded.

There is no partial success: one failed element fails the step. To tolerate individual failures, have the worker report a result that describes the failure instead of an error.

Compensation

A compensate block on a for step runs once per element that succeeded, newest first, together with the other compensations of the workflow. Inside the block, a reference to the step (reserve.reservation_id above) is the output of the element being compensated, not the list, and the loop variable is bound to that element. Each element’s compensation is a unit keyed compensate:reserve[<index>]. See Compensation.

Combining with other members

Filtering

for has no per-element filter clause (such as for x in xs where ...). To process only some elements, iterate over a filtered list, written with the built-in filter and a lambda:

import "contracts.orbit"

workflow ReserveInStock {
    version "1.0.0"
    input { order_id: String, items: List<LineItem> }

    step reserve {
        for item in filter(input.items, i => i.quantity > 0)
        worker "inventory.reserve"
        with { order_id: input.order_id, items: [item] }
    }
}

A lambda makes the workflow compile to orbit-ir/2 (Versioning). See Built-in functions.

See also

• Steps
• Child workflows
• Compensation
• Idempotency
• Fan-out and child workflows guide

Child workflows

A workflow step starts another workflow as a durable child execution and waits for its result. Child workflows let you reuse a workflow as a typed building block: the parent’s input to the child and the child’s result are checked at compile time, and the runtime links parent and child so that a crash never starts a child twice or loses its result. This page covers the workflow action, its typing, the runtime behavior, and its restrictions.

Declaring a child workflow step

workflow Shipping {
    version "1.0.0"
    input { order_id: String, items: Int }
    output { carrier: String, tracking: String }

    step quote { worker "shipping.quote" with { order_id: input.order_id, items: input.items } }
    step book { worker "shipping.book" with { order_id: input.order_id, carrier: quote.carrier } }

    return { carrier: quote.carrier, tracking: book.tracking }
}

workflow Fulfilment {
    version "1.0.0"
    input { order_id: String, items: List<LineItem> }

    step ship {
        workflow "Shipping"
        with { order_id: input.order_id, items: len(input.items) }
        timeout 1h
    }

    return { tracking: ship.tracking }
}

The name after workflow is a string literal naming a workflow in the same compilation: declared in the same file or in an imported file. An unknown name is E0312, with a suggestion:

error[E0312]: unknown workflow `Shiping`

Typing

The child’s declared input plays the role of a task contract’s input, and its output (declared or inferred) plays the role of the contract’s output:

• with is checked against the child’s input. A child whose input has required fields needs a with (E0403).
• A reference to the step has the child’s output type: ship.tracking is a String above.
• when makes the reference optional, and for makes it a list, exactly as for task steps. See Steps.

Allowed members

workflow Child {
    version "1.0.0"
}

workflow Parent {
    version "1.0.0"
    step run {
        workflow "Child"
        retry { attempts: 3 }
    }
}

error[E0307]: `retry` is not allowed in a `workflow` step
 --> parent.orbit:9:9
  |
9 |         retry { attempts: 3 }
  |         ^^^^^^^^^^^^^^^^^^^^^
  = note: child workflows are durable; put retries on the child's own steps

error: compilation failed: 1 error(s), 0 warning(s)

A child execution is durable on its own and has its own steps, retries, timeouts and compensation. Configure reliability inside the child.

Cycles

Workflows cannot start each other in a cycle, directly or indirectly (E0311):

workflow Ping {
    version "1.0.0"
    step pong { workflow "Pong" }
}

workflow Pong {
    version "1.0.0"
    step ping { workflow "Ping" }
}

error[E0311]: workflows call each other in a cycle
 --> ping.orbit:3:26
  |
3 |     step pong { workflow "Pong" }
  |                          ^^^^^^
8 |     step ping { workflow "Ping" }
  |                          ------ `Pong` starts `Ping`
  = note: cycle: Ping -> Pong -> Ping
  = help: a workflow cannot (directly or indirectly) start itself as a child

error: compilation failed: 1 error(s), 0 warning(s)

The compiler orders workflows so that every child comes before the workflows that start it. orbit deploy and orbit run register definitions in that order.

Execution

When a workflow step is scheduled, the runtime evaluates with and starts the child execution itself; no worker is involved.

The runtime reconciles parents and children continuously, so a crash at any point neither duplicates nor loses a child.

Failure

None of these is retried, because workflow steps take no retry policy. A failed workflow step aborts the parent like any other failed step.

Cancellation

When the parent is aborted (a step failed, it was cancelled, or it timed out), the runtime cancels every running child of that parent. A cancelled child runs its own compensations before it ends.

Registering parents and children

A parent pins the definition hash of the child it was compiled against. Registering a parent fails with CHILD_NOT_REGISTERED if that exact child definition is not registered yet. orbit deploy registers children first.

Because the child’s hash is part of the parent’s definition, changing the child changes the parent’s definition hash too. After you change a child, bump the version of every workflow that starts it; otherwise registering the parent fails with DEFINITION_CONFLICT. See Versioning.

See also

• Steps
• Fan-out
• Compensation
• Versioning
• Fan-out and child workflows guide

Signals and queries

Signals and queries connect a running execution to the outside world. A signal is a typed message that a person or another system sends to an execution, such as a reviewer’s decision; an await step waits for it durably. A query is a typed, read-only view of an execution’s state that anyone can evaluate at any time, such as “where does this order stand?”. Both are declared in the workflow, so the compiler checks every use of them, and the runtime validates every signal payload before it is recorded. This page covers declarations, await steps, buffering and ordering, timeouts, sending and querying from the CLI, HTTP and the SDKs, typing rules, errors and history events, and ends with a complete example.

Overview

workflow Approval {
    version "1.0.0"
    input { request_id: String }

    signal review { approved: Bool, reviewer: String, comment: String? }

    step decision {
        await review
        timeout 2d
    }

    query status = {
        decided: !is_null(decision)
        approved: decision.approved
    }

    return { approved: decision.approved, reviewer: decision.reviewer }
}

Sending a signal and evaluating a query need an execution id and the declared name:

$ orbit signal <execution-id> review --data '{"approved": true, "reviewer": "dana"}'
$ orbit query <execution-id> status

Declaring a signal

signal <name> { <fields> }

A signal declaration is a workflow member. <name> is an identifier, unique among the workflow’s signals (E0317). The body is a record, written exactly like a workflow input block: fields with types, optional fields (T?) and constant defaults. Field types can be schemas, lists and maps:

schema Reviewer {
    name: String
    team: String = "operations"
}

workflow Exceptions {
    version "1.0.0"
    timeout 30d

    signal review {
        approved: Bool
        by: Reviewer
        comment: String?
        tags: List<String> = []
    }

    step decision { await review }

    return { approved: decision.approved, team: decision.by.team }
}

Signal names and step names are separate namespaces, and so are query names. A workflow can declare any number of signals. A signal that no step awaits is warning W0605 (see Static safety checks).

How the runtime validates a payload

When a signal arrives, the runtime:

1. applies the declared defaults to missing fields, including nested schema fields,
2. checks the payload against the declared type and rejects it with 422 SIGNAL_PAYLOAD_INVALID if a required field is missing or a value has the wrong type; the message names the path, for example payload for signal `review` is invalid at $.approved: expected Bool, found a string,
3. records the validated payload in the history.

Fields that the declaration does not list are accepted and kept in the recorded payload. (Workflow inputs are stricter: an execution input with an undeclared field is rejected.) An optional field that is not sent stays absent from the payload; reading it gives null.

Waiting for a signal: await

step <name> { await <signal> [timeout DURATION] [after ...] [when ...] }

await <signal> is a step action, like worker or sleep. It names a signal declared in the same workflow; an unknown name is E0315, with a suggestion for a close misspelling. When the step becomes eligible, the runtime records SignalAwaitStarted and the unit is WAITING. When a signal of that name is available, the runtime records SignalDelivered and the step succeeds with the signal’s payload as its output.

The step’s output type is the signal’s record type, so later steps read the payload fields directly:

task "refunds.issue" {
    input { order_id: String, amount: Float, note: String }
    output { refund_id: String }
}

workflow RefundRequest {
    version "1.0.0"
    input { order_id: String, amount: Float }

    signal decision { approved: Bool, note: String = "" }

    step review {
        await decision
        timeout 3d
    }

    step refund {
        worker "refunds.issue"
        when review.approved
        with { order_id: input.order_id, amount: input.amount, note: review.note }
    }

    return { approved: review.approved, refund_id: refund.refund_id }
}

Members of an await step

An await step needs no worker, so most members do not apply:

workflow Approvals {
    version "1.0.0"
    input { reviewers: List<String> }
    signal review { approved: Bool }
    step decision {
        await review
        timeout 2d
        retry { attempts: 3 }
        with { reviewer: "dana" }
    }
}

error[E0307]: `retry` is not allowed in an `await` step
 --> approvals.orbit:8:9
  |
8 |         retry { attempts: 3 }
  |         ^^^^^^^^^^^^^^^^^^^^^

error[E0307]: `with` is not allowed in an `await` step
 --> approvals.orbit:9:14
  |
9 |         with { reviewer: "dana" }
  |              ^^^^^^^^^^^^^^^^^^^^

error: compilation failed: 2 error(s), 0 warning(s)

Output type

Reading a field of an optional record gives an optional value, so decision.approved has type Bool? when decision has a when condition. Use coalesce(decision.approved, false) where a Bool is required.

Buffering and ordering

Signals are buffered per execution. The runtime accepts a signal at any time while the execution is not terminal, whether or not a step is waiting for it:

• A signal that arrives before its await step starts is kept in the buffer. When the step starts waiting, it takes the buffered signal right away.
• Each await step takes the oldest signal of its name that no step has taken yet. Signals of one name are therefore delivered in the order they were received.
• Each signal is delivered to at most one step. Two steps that wait for the same signal at the same time never receive the same signal.
• A signal that no step takes stays in the buffer, undelivered. It is ignored when the execution finishes.

The buffer is part of the execution state, in the signals array of GET /v1/executions/{id} and orbit inspect <id> (see Executions and history).

In this workflow, both signals are sent while the first step is still sleeping:

workflow Batch {
    version "1.0.0"
    timeout 1h

    signal item { sku: String, quantity: Int = 1 }

    step pause { sleep 2s }
    step first { await item after pause }
    step second { await item after first }

    return { skus: [first.sku, second.sku], total: first.quantity + second.quantity }
}

$ orbit run batch.orbit --id batch-1 --no-wait
$ orbit signal batch-1 item --data '{"sku": "A-1"}'
signal `item` recorded for batch-1 (history #4); the next `await item` step takes it
$ orbit signal batch-1 item --data '{"sku": "B-2", "quantity": 3}'
signal `item` recorded for batch-1 (history #5); the next `await item` step takes it
$ orbit status batch-1
COMPLETED batch-1  Batch@1.0.0
  elapsed: 2.0s

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  first                        SUCCEEDED          1      0ms  
  pause                        SUCCEEDED          1     2.0s  
  second                       SUCCEEDED          1      0ms  

  output: {"skus":["A-1","B-2"],"total":4}
$ orbit logs batch-1
+     0ms   #1  WorkflowCreated           
+     0ms   #2  WorkflowStarted           
+     1ms   #3  TimerStarted              step=pause
+    13ms   #4  SignalReceived            name=item
+    24ms   #5  SignalReceived            name=item
+    2.0s   #6  TimerFired                step=pause
+    2.0s   #7  SignalAwaitStarted        step=first signal=item
+    2.0s   #8  SignalDelivered           step=first signal_seq=4
+    2.0s   #9  SignalAwaitStarted        step=second signal=item
+    2.0s  #10  SignalDelivered           step=second signal_seq=5
+    2.0s  #11  WorkflowCompleted         

first received the first signal and second the second one. The default quantity: Int = 1 was applied to the first payload.

orbit signal reports success (signal ... recorded for <id>) as soon as the runtime has recorded and buffered the signal, whether or not a step is waiting for it. The SignalDelivered event shows when a step took it.

Timeouts

timeout on an await step bounds the wait. If no signal of that name is available when the timeout passes, the step fails with the non-retryable error SIGNAL_TIMEOUT, and the execution aborts like after any other step failure: work that has not started is withdrawn and succeeded steps are compensated, newest first. See Compensation.

task "payments.charge" {
    input { order_id: String, amount: Float }
    output { transaction_id: String }
}

task "payments.refund" {
    input { transaction_id: String, amount: Float }
    output { refunded: Bool }
}

workflow ConfirmCharge {
    version "1.0.0"
    input { order_id: String, amount: Float }

    signal confirm { ok: Bool }

    step charge {
        worker "payments.charge"
        with { order_id: input.order_id, amount: input.amount }
        compensate {
            worker "payments.refund"
            with { transaction_id: charge.transaction_id, amount: input.amount }
        }
    }

    step confirmation {
        await confirm
        after charge
        timeout 2s
    }
}

With no confirm signal sent:

$ orbit logs confirm-1
+     0ms   #1  WorkflowCreated           
+     0ms   #2  WorkflowStarted           
+     1ms   #3  StepScheduled             step=charge attempt=1
+     3ms   #4  StepDispatched            step=charge attempt=1 worker_id=orders-python
+    12ms   #5  StepSucceeded             step=charge attempt=1
+    14ms   #6  SignalAwaitStarted        step=confirmation signal=confirm
+    2.0s   #7  StepFailed                step=confirmation error=SIGNAL_TIMEOUT no `confirm` signal arrived before the step's timeout
+    2.0s   #8  CompensationStarted       reason=step `confirmation` failed: no `confirm` signal arrived before the step's timeout
+    2.0s   #9  StepScheduled             step=compensate:charge attempt=1
+    2.0s  #10  StepDispatched            step=compensate:charge attempt=1 worker_id=orders-python
+    2.0s  #11  StepSucceeded             step=compensate:charge attempt=1
+    2.0s  #12  CompensationCompleted     
+    2.0s  #13  WorkflowFailed            error=SIGNAL_TIMEOUT step `confirmation` failed: no `confirm` signal arrived before the step's timeout

The deadline is recorded in SignalAwaitStarted (deadline_ms) and in the unit’s wake_at_ms, so it survives runtime restarts. A deadline that passed while the runtime was down is handled right after startup.

Without a step timeout, the step waits until a signal arrives, the workflow timeout passes, or the execution is cancelled. An await step with neither a step timeout nor a workflow timeout is warning W0606, because the execution could wait forever.

Cancellation and other aborts

An await step that is waiting when the execution is cancelled, times out, or fails elsewhere is withdrawn: the runtime records StepCancelled and the unit ends CANCELLED. Signals sent during an abort are still validated and recorded, but no step takes them. Once the execution is terminal, sending a signal fails with 409 EXECUTION_FINISHED.

$ orbit cancel order-A-103 --reason "order withdrawn"
cancellation requested; execution is CANCELLED
$ orbit logs order-A-103 | tail -5
+   312ms   #5  CancelRequested           reason=order withdrawn
+   313ms   #6  StepCancelled             step=decision
+   313ms   #7  StepCancelled             step=charge
+   313ms   #8  StepCancelled             step=notify
+   313ms   #9  WorkflowCancelled         

Sending a signal

Signals are sent by name to one execution. Sending requires the admin credential when authentication is enabled, like every other execution endpoint.

CLI

orbit signal <EXECUTION_ID> <NAME> [--data <JSON> | --data @<file>]

--data is the payload as JSON (default {}); @path reads it from a file. On success the command prints the history sequence number of the recorded SignalReceived event:

$ orbit signal order-A-100 review --data '{"approved": true, "reviewer": "dana"}'
signal `review` recorded for order-A-100 (history #5); the next `await review` step takes it
$ orbit signal order-A-100 review --data @review.json

See CLI: orbit signal.

HTTP

POST /v1/executions/{id}/signals/{name}
content-type: application/json

{"approved": true, "reviewer": "dana"}

The body is the payload. A request without a body sends {}. Response 200:

{"execution_id": "order-A-100", "signal": "review", "accepted": true, "seq": 5}

See HTTP API.

Python and TypeScript

import os

from orbit_sdk import Client

client = Client(token=os.environ["ORBIT_ADMIN_TOKEN"])
seq = client.signal("order-A-100", "review", {"approved": True, "reviewer": "dana"})

import { Client } from "orbit-lang";

const client = new Client({ token: process.env.ORBIT_ADMIN_TOKEN });
const seq = await client.signal("order-A-100", "review", { approved: true, reviewer: "dana" });

Both return the sequence number and raise (ApiError) on an error response. See Python and TypeScript.

Errors

Signals are checked against the definition the execution is pinned to, not against the latest registered version of the workflow.

Queries

query <name> = <expression>

A query declaration is a workflow member. <name> is an identifier, unique among the workflow’s queries (E0318). The expression can read input, execution and the output of any step:

workflow Progress {
    version "1.0.0"
    input { items: List<String> }

    step count { compute len(input.items) }
    step pause { sleep 1h after count }

    query summary = {
        id: execution.id
        items: coalesce(count, 0)
        paused: !is_null(pause)
    }
}

Typing rules

A query can be evaluated at any moment, so any step may not have run yet. The compiler therefore types every step output as optional in a query: a step whose output is T is T? there (and a step that is already optional stays optional). The query’s result type is the type of the expression under that rule, and it is recorded in the compiled definition.

workflow Progress {
    version "1.0.0"
    input { items: List<String> }
    step count { compute len(input.items) }
    query remaining = count + 1
}

error[E0406]: operator `+` cannot be applied to `Int?` and `Int`
 --> progress.orbit:5:23
  |
5 |     query remaining = count + 1
  |                       ^^^^^^^^^
  |                       ----- `Int?`
  |                               - `Int`
  = help: one operand may be `null`; use `coalesce(value, default)` first

error: compilation failed: 1 error(s), 0 warning(s)

Use coalesce and is_null to handle steps that have not run. Field access on an optional record is allowed and gives null when the record is null, so decision.approved is null until decision succeeds.

Queries are not steps: they add no dependencies, cannot be read by steps or return, and do not appear in the step graph.

Evaluation

The runtime evaluates a query when it is asked, against the execution’s current state:

• input is the execution input, with defaults applied.
• A step that has succeeded reads as its output. A step that has not succeeded (pending, waiting, running, skipped, failed or cancelled) reads as null.
• execution.id, execution.workflow and execution.version are available as in other expressions.

Evaluating a query is read-only. It records nothing in the history and does not change the execution. It works on running and on finished executions, so you can still read a query after the execution completes. An expression error at evaluation time, such as a division by zero, returns 422 QUERY_FAILED with the cause; nothing is recorded.

Reading a query

$ orbit query order-A-100 status
{
  "needs_approval": true,
  "approved": null,
  "reviewer": null,
  "charged": false
}

GET /v1/executions/{id}/queries/{name}

{"execution_id":"order-A-100","query":"status","value":{"needs_approval":true,"approved":true,"reviewer":"dana","charged":true}}

state = client.query("order-A-100", "status")

const state = await client.query<{ approved: boolean | null }>("order-A-100", "status");

orbit query prints the value only. The SDK methods return the value.

History events

A timed-out wait is recorded as StepFailed with SIGNAL_TIMEOUT, and a withdrawn wait as StepCancelled. Queries record no events. See Executions and history.

Complete example

examples/approval.orbit charges an order. Orders of 1000 or more wait for a reviewer’s review signal; the status query reports where an order stands. The assess step is a compute step, evaluated by the runtime. It runs with the example Python and TypeScript workers.

// Human-in-the-loop approval with typed signals, queries and compute steps.
//
// Orders of 1000 or more wait for a reviewer's decision, sent as a typed
// `review` signal (`orbit signal <id> review --data '{...}'`). Anyone can ask
// where an order stands with the `status` query (`orbit query <id> status`).
//
// Workers: examples/workers/python/order_workers.py and
// examples/workers/typescript/order_workers.ts.

import "contracts.orbit"

workflow OrderApproval {
    version "1.0.0"
    description "Charge an order, with a reviewer's approval above a threshold"
    input { order_id: String, customer_id: String, amount: Float, currency: String = "USD" }
    output { status: String, transaction_id: String? }

    signal review { approved: Bool, reviewer: String, comment: String? }

    // Deterministic logic, evaluated by the runtime: no worker needed.
    step assess {
        compute {
            needs_approval: input.amount >= 1000.0
            rounded: float(int(input.amount * 100.0)) / 100.0
        }
    }

    step decision {
        await review
        when assess.needs_approval
        timeout 2d
    }

    step charge {
        worker "payments.charge"
        using python
        when !assess.needs_approval || coalesce(decision.approved, false)
        with { order_id: input.order_id, amount: assess.rounded, currency: input.currency }
        idempotency_key: "charge-" + input.order_id
        compensate {
            worker "payments.refund"
            with { transaction_id: charge.transaction_id, amount: assess.rounded }
        }
    }

    step notify {
        worker "notifications.send"
        after charge
        with {
            customer_id: input.customer_id
            message: if is_null(charge) then "Your order was not approved" else "Your order is confirmed"
        }
    }

    query status = {
        needs_approval: assess.needs_approval
        approved: decision.approved
        reviewer: decision.reviewer
        charged: !is_null(charge)
    }

    return {
        status: if is_null(charge) then "rejected" else "charged"
        transaction_id: charge.transaction_id
    }
}

decision has a when condition, so its output is optional: charge reads coalesce(decision.approved, false). When charge is skipped, notify still runs (a skipped dependency counts as done), and is_null(charge) selects the message.

Start the runtime and the example workers:

$ orbit server --db orbit.db
$ PYTHONPATH=sdks/python python3 examples/workers/python/order_workers.py
$ node examples/workers/typescript/order_workers.ts

Start an order that needs approval, and look at it while it waits:

$ orbit run examples/approval.orbit --id order-A-100 --input '{"order_id": "A-100", "customer_id": "c-7", "amount": 2500.0}' --no-wait
deployed OrderApproval@1.0.0 (sha256:939fd564b818)
started execution order-A-100
order-A-100
$ orbit status order-A-100
RUNNING order-A-100  OrderApproval@1.0.0
  elapsed: 1ms

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  assess                       SUCCEEDED          1           
  decision                     WAITING            1           
$ orbit query order-A-100 status
{
  "needs_approval": true,
  "approved": null,
  "reviewer": null,
  "charged": false
}

A payload with the wrong type is rejected and nothing is recorded:

$ orbit signal order-A-100 review --data '{"approved": "yes", "reviewer": "dana"}'
error: SIGNAL_PAYLOAD_INVALID (422): payload for signal `review` is invalid at $.approved: expected Bool, found a string

Send the decision:

$ orbit signal order-A-100 review --data '{"approved": true, "reviewer": "dana", "comment": "verified by phone"}'
signal `review` recorded for order-A-100 (history #5); the next `await review` step takes it
$ orbit status order-A-100
COMPLETED order-A-100  OrderApproval@1.0.0
  elapsed: 569ms

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  assess                       SUCCEEDED          1           
  decision                     SUCCEEDED          1    539ms  
  charge                       SUCCEEDED          1      9ms  worker orders-python
  notify                       SUCCEEDED          1      6ms  worker orders-typescript

  output: {"status":"charged","transaction_id":"tx-A-100"}
$ orbit query order-A-100 status
{
  "needs_approval": true,
  "approved": true,
  "reviewer": "dana",
  "charged": true
}

The history shows the wait, the signal and its delivery. assess is a compute step, so it succeeds without being scheduled or dispatched:

$ orbit logs order-A-100
+     0ms   #1  WorkflowCreated           
+     0ms   #2  WorkflowStarted           
+     1ms   #3  StepSucceeded             step=assess attempt=1
+     1ms   #4  SignalAwaitStarted        step=decision signal=review
+   538ms   #5  SignalReceived            name=review
+   540ms   #6  SignalDelivered           step=decision signal_seq=5
+   540ms   #7  StepScheduled             step=charge attempt=1
+   547ms   #8  StepDispatched            step=charge attempt=1 worker_id=orders-python
+   556ms   #9  StepSucceeded             step=charge attempt=1
+   557ms  #10  StepScheduled             step=notify attempt=1
+   562ms  #11  StepDispatched            step=notify attempt=1 worker_id=orders-typescript
+   568ms  #12  StepSucceeded             step=notify attempt=1
+   569ms  #13  WorkflowCompleted         
$ orbit logs order-A-100 --json | grep Signal
{"seq":4,"timestamp_ms":1794746714132,"type":"SignalAwaitStarted","step":"decision","signal":"review","deadline_ms":1794919514132}
{"seq":5,"timestamp_ms":1794746714669,"type":"SignalReceived","name":"review","payload":{"approved":true,"reviewer":"dana","comment":"verified by phone"}}
{"seq":6,"timestamp_ms":1794746714671,"type":"SignalDelivered","step":"decision","signal_seq":5}

A rejection skips the charge:

$ orbit run OrderApproval --id order-A-101 --input '{"order_id": "A-101", "customer_id": "c-8", "amount": 4000.0}' --no-wait
$ orbit signal order-A-101 review --data '{"approved": false, "reviewer": "lee", "comment": "customer could not be reached"}'
signal `review` recorded for order-A-101 (history #5); the next `await review` step takes it
$ orbit status order-A-101
COMPLETED order-A-101  OrderApproval@1.0.0
  elapsed: 328ms

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  assess                       SUCCEEDED          1           
  charge                       SKIPPED            0           
  decision                     SUCCEEDED          1    315ms  
  notify                       SUCCEEDED          1      5ms  worker orders-typescript

  output: {"status":"rejected","transaction_id":null}

A small order needs no approval: decision is skipped and the order is charged straight away:

$ orbit run OrderApproval --id order-A-102 --input '{"order_id": "A-102", "customer_id": "c-9", "amount": 120.0}'
started execution order-A-102
  ✓ assess                         succeeded 
  ↷ decision                       skipped 
  ✓ charge                         succeeded 7ms
  ✓ notify                         succeeded 9ms

COMPLETED order-A-102  OrderApproval@1.0.0
  elapsed: 22ms
{
  "status": "charged",
  "transaction_id": "tx-A-102"
}

Changing signals and queries

Signals and queries are part of the workflow definition and its hash. Adding, removing or changing one requires a new workflow version, and executions keep the signals and queries of the version they started with. Senders and readers depend on them like callers depend on the input, so orbit compat reports a removed signal or query, a signal payload change that would reject payloads that used to be valid, and a query result change that readers may not expect. See Compatibility checks.

A workflow that declares a signal or a query compiles to orbit-ir/2. See Versioning.

See also

• Steps
• Compute steps
• Static safety checks
• Executions and history
• HTTP API
• CLI

Compute steps

A compute step evaluates an expression in the runtime and makes the value its output. It needs no worker, so it suits the small, deterministic pieces of logic that sit between tasks: deriving a flag, totalling a list, reshaping a record, picking the items that need attention. This page covers when to use a compute step instead of a worker, the syntax and members, how the runtime evaluates it, lambdas and collection functions, fan-out, conditions and errors.

When to use a compute step

A compute step can do nothing that an expression in a later step’s with or when could not. What it adds is a name: the intermediate result is computed once, recorded in the history, and read by any number of later steps, the return expression and queries.

Declaring a compute step

step <name> { compute <expression> }

task "payments.charge" {
    input { order_id: String, amount: Float }
    output { transaction_id: String }
}

workflow Checkout {
    version "1.0.0"
    input { order_id: String, amount: Float, coupon_percent: Int = 0 }

    step pricing {
        compute {
            discount: input.amount * float(input.coupon_percent) / 100.0
            needs_review: input.amount >= 1000.0
        }
    }

    step charge {
        worker "payments.charge"
        when !pricing.needs_review
        with { order_id: input.order_id, amount: input.amount - pricing.discount }
    }

    return { charged: !is_null(charge), discount: pricing.discount }
}

The expression can be of any type, not only a record. The compiler infers the step’s output type from it, and later steps, return and queries see that type: here pricing is { discount: Float, needs_review: Bool }, and step total { compute sum(input.prices) } would make total a Float.

The expression can read input, execution, the outputs of other steps and, in a for step, the loop variable. Reading a step’s output makes the compute step depend on it, exactly as in with. See Dependencies.

Members

workflow Totals {
    version "1.0.0"
    input { prices: List<Float> }
    step total {
        compute sum(input.prices)
        timeout 10s
        compensate { worker "ledger.reverse" }
    }
}

error[E0307]: `timeout` is not allowed in a `compute` step
 --> totals.orbit:6:17
  |
6 |         timeout 10s
  |                 ^^^

error[E0308]: a `compute` step has nothing to compensate
 --> totals.orbit:7:9
  |
7 |         compensate { worker "ledger.reverse" }
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: compilation failed: 2 error(s), 0 warning(s)

A step has exactly one action, so compute cannot be combined with worker, workflow, sleep or await (E0106).

How it runs

When every dependency of a compute step is done and its when condition is true, the runtime evaluates the expression during the same decision and records the value as the step’s output in a StepSucceeded event, with attempt: 1. There is no StepScheduled or StepDispatched event, no worker, no idempotency key and no retry.

In this history, assess is a compute step and charge a worker task:

$ orbit logs order-A-100
+     0ms   #1  WorkflowCreated           
+     0ms   #2  WorkflowStarted           
+     1ms   #3  StepSucceeded             step=assess attempt=1
+     1ms   #4  SignalAwaitStarted        step=decision signal=review
...
+   540ms   #7  StepScheduled             step=charge attempt=1
+   547ms   #8  StepDispatched            step=charge attempt=1 worker_id=orders-python
+   556ms   #9  StepSucceeded             step=charge attempt=1

Lambdas and collection functions

Collection functions take a list and a lambda, a one-parameter function written name => expression:

A lambda is only allowed as the second argument of map, filter, find, any and all (E0415 elsewhere), and its parameter must not reuse the name of a step, a loop variable, an enclosing lambda parameter, input or execution (E0413). Lambdas and these functions work in every expression, not only in compute steps. See Built-in functions for signatures and details, and Expressions for the syntax.

schema Line {
    sku: String
    quantity: Int
    unit_price: Float
}

workflow Totals {
    version "1.0.0"
    input { lines: List<Line> }

    step totals {
        compute {
            count: len(input.lines)
            units: sum(map(input.lines, l => l.quantity))
            subtotal: sum(map(input.lines, l => float(l.quantity) * l.unit_price))
            bulk: filter(input.lines, l => l.quantity >= 10)
            first_free: find(input.lines, l => l.unit_price == 0.0)
            all_in_stock: all(input.lines, l => l.quantity > 0)
        }
    }

    step line_totals {
        for line in input.lines
        compute { sku: line.sku, total: float(line.quantity) * line.unit_price }
    }

    step per_unit {
        compute totals.subtotal / float(totals.units)
        when totals.units > 0
    }

    return {
        units: totals.units
        subtotal: totals.subtotal
        bulk_skus: map(totals.bulk, l => l.sku)
        free_sku: totals.first_free.sku
        line_totals: line_totals
        per_unit: per_unit
    }
}

$ orbit run totals.orbit --id totals-1 --input '{"lines": [{"sku": "A", "quantity": 12, "unit_price": 2.5}, {"sku": "B", "quantity": 1, "unit_price": 0.0}]}'
deployed Totals@1.0.0 (sha256:01f95045bc38)
started execution totals-1
  ✓ line_totals                    succeeded 0ms
  ✓ line_totals[0]                 succeeded 
  ✓ line_totals[1]                 succeeded 
  ✓ per_unit                       succeeded 
  ✓ totals                         succeeded 

COMPLETED totals-1  Totals@1.0.0
  elapsed: 2ms
{
  "units": 13,
  "subtotal": 30.0,
  "bulk_skus": [
    "A"
  ],
  "free_sku": "B",
  "line_totals": [
    {
      "sku": "A",
      "total": 30.0
    },
    {
      "sku": "B",
      "total": 0.0
    }
  ],
  "per_unit": 2.3076923076923075
}

first_free has type Line?, because find may find nothing, so totals.first_free.sku is a String?.

Fan-out

With for x in list, a compute step evaluates its expression once per element, with x bound to the element. As for task steps, the runtime records StepFanOut, then one unit per element (line_totals[0], line_totals[1], …), each with its own StepSucceeded, and finally the step’s output: the list of element values, in input order. The output type is List<T>, where T is the type of the expression.

+     2ms   #4  StepFanOut                step=line_totals
+     2ms   #5  StepSucceeded             step=line_totals[0] attempt=1
+     2ms   #6  StepSucceeded             step=line_totals[1] attempt=1
+     2ms   #7  StepSucceeded             step=per_unit attempt=1
+     2ms   #8  StepSucceeded             step=line_totals attempt=1

If any element fails, the step fails. See Fan-out.

Conditions

A compute step with when is skipped when the condition is false or null, and its output is null. Its output type is optional (T?, or List<T>? with for), so readers use coalesce or is_null. In the example above, per_unit is skipped for an empty order, which avoids a division by zero. See Conditions.

Errors

The type checker reports type errors in the expression as usual, mostly E0400 (type mismatch), E0405 (optional value where a value is required), E0406 (operator not defined) and E0407 (unknown function or wrong number of arguments).

Some errors can only happen at runtime: division by zero, integer overflow, a failed conversion such as int("abc"), or an operation on a JSON value of the wrong shape. Such an error fails the step (or the element) with the non-retryable code EXPRESSION_ERROR and the message evaluating `compute`: <cause>. The execution then aborts and compensates like after any other step failure.

workflow Discount {
    version "1.0.0"
    input { subtotal: Float, discount_percent: Int = 0 }

    step factor {
        compute input.subtotal * float(100 / (100 - input.discount_percent))
    }
}

$ orbit run discount.orbit --id discount-1 --input '{"subtotal": 10.0, "discount_percent": 100}'
deployed Discount@1.0.0 (sha256:910bcb4107fa)
started execution discount-1
  ✗ factor                         failed evaluating `compute`: division by zero

FAILED discount-1  Discount@1.0.0
  elapsed: 1ms
  compensation: none
  error: EXPRESSION_ERROR step `factor` failed: evaluating `compute`: division by zero

IR version

A workflow with a compute step, or with a lambda anywhere, compiles to orbit-ir/2. See Versioning.

See also

• Expressions
• Built-in functions
• Steps
• Signals and queries
• Fan-out

Compensation

A compensate block declares the business action that undoes a step, such as refunding a payment or releasing reserved stock. When a workflow fails, is cancelled or times out, the runtime runs the compensation of every step that succeeded, newest first. This is the Saga pattern: compensation is explicit business logic, not a database rollback. This page covers the syntax, what a compensation can read, when compensations run, and how their outcome is recorded.

Declaring a compensation

workflow Order {
    version "1.0.0"
    input { order_id: String, amount: Float, items: List<LineItem> }

    step reserve {
        worker "inventory.reserve"
        with { order_id: input.order_id, items: input.items }
        compensate {
            worker "inventory.release"
            with { reservation_id: reserve.reservation_id }
        }
    }

    step charge {
        worker "payments.charge"
        after reserve
        with { order_id: input.order_id, amount: input.amount, currency: "USD" }
        compensate {
            worker "payments.refund"
            with { transaction_id: charge.transaction_id, amount: input.amount }
            idempotency_key: "refund-" + charge.transaction_id
            retry { attempts: 10, backoff: exponential, initial_delay: 1s, max_delay: 1m }
        }
    }

    step confirm {
        worker "notifications.send"
        after charge
        with { customer_id: input.order_id, message: "Order confirmed" }
    }
}

If confirm fails permanently, the runtime refunds the charge and then releases the reservation.

Members of a compensate block

A compensate block is a small task step without its own scheduling:

Steps that can have a compensation: task steps and workflow steps. A sleep step has nothing to compensate (E0308). Declare at most one compensate block per step.

What a compensation can read

A compensation expression can read:

• input and execution,
• the step’s own output, which is not optional here, even if the step has a when condition, because only succeeded steps are compensated,
• the outputs of the steps the step depends on, directly or transitively (with their usual, possibly optional, types),
• in a for step, the loop variable, bound to the element being compensated.

In a for step, a reference to the step itself is the output of the element being compensated, not the list. See Fan-out.

Reading any other step is E0308, because that step may not have run when the compensated step did:

task "a.run" {
    input { n: Int }
    output { v: Int }
}

task "a.undo" {
    input { v: Int }
    output { ok: Bool }
}

workflow Undo {
    version "1.0.0"
    step first { worker "a.run" with { n: 1 } }
    step second {
        worker "a.run"
        with { n: 2 }
        compensate { worker "a.undo" with { v: first.v } }
    }
}

error[E0308]: step `first` cannot be referenced here
  --> undo.orbit:17:48
   |
17 |         compensate { worker "a.undo" with { v: first.v } }
   |                                                ^^^^^
   = note: a compensation for `second` can only read `second` and the steps it depends on

error: compilation failed: 1 error(s), 0 warning(s)

Add after first to second to make first an ancestor, and the reference becomes valid.

Compensation references do not add dependencies to the step graph.

When compensations run

Compensation starts when the workflow is aborted, for any of these reasons:

The runtime then proceeds in this order:

1. Withdraw work that has not started: pending and queued units, timers, await steps waiting for a signal, and retries waiting for their delay become CANCELLED.
2. Wait for attempts that are in flight. They may still succeed, and a step that succeeds now also needs compensating. Failed attempts are not retried while the workflow is aborting.
3. Compensate every unit that succeeded and has a compensate block, one at a time, in reverse order of completion (the step that finished last is compensated first). Each element of a for step is a separate unit.
4. Finish with the final status and a compensation outcome.

Steps that were skipped, failed, cancelled or never started are not compensated. Steps without a compensate block are ignored.

A workflow that fails while evaluating its return value, after all steps succeeded, ends FAILED without compensation.

Compensation outcome

Every failed, cancelled or timed-out execution records how compensation went:

A compensation that fails permanently does not stop the others: the runtime keeps undoing the remaining steps, newest first, so as few effects as possible are left behind. When every compensation has run, it records one CompensationFailed event per failed compensation and ends the execution with compensation: failed. The history shows exactly which steps were undone and which were not, so an operator can finish the cleanup. Give compensations generous retry policies for that reason. (Version 0.1.0 stopped at the first failed compensation.)

Compensation in the history

For a workflow with two compensated steps, first and second, followed by a step broken that fails, orbit logs shows:

+   705ms  #20  StepFailed                step=broken error=HTTP_ERROR ...
+   705ms  #21  CompensationStarted       reason=step `broken` failed: ...
+   705ms  #22  StepScheduled             step=compensate:second attempt=1
+   806ms  #24  StepSucceeded             step=compensate:second attempt=1
+   808ms  #25  StepScheduled             step=compensate:first attempt=1
+   905ms  #27  StepSucceeded             step=compensate:first attempt=1
+   907ms  #28  CompensationCompleted
+   907ms  #29  WorkflowFailed            error=HTTP_ERROR step `broken` failed: ...

Compensation units are keyed compensate:<unit>, for example compensate:charge or compensate:reserve[2].

Designing compensations

• Declare compensated_by on contracts whose effect must be undone. The compiler then warns about every step that calls the task without the matching compensation (W0601, W0602). See Static safety checks.

• Make compensations idempotent. They are delivered at least once, like any task, and their key is stable.

• Prefer business actions with clear semantics (refund, release, cancel) over attempts to restore previous state.

• A compensation can only read data that existed when the step completed. If undoing needs an identifier, return it from the step.

• Compensation is not available for side effects that cannot be undone, such as a sent email. Order such steps last.

See also

• Orders with compensation guide
• Steps
• Fan-out
• Retries and timeouts
• Static safety checks
• Executions and history

Outcome handlers

An outcome handler is a block of steps that runs when an execution ends badly: on failure when a step fails permanently, on cancel when the execution is cancelled, and on timeout when the workflow’s timeout passes. Handlers run after compensation has finished and before the execution records its terminal status, so they are the place to tell a customer, page an operator or record an audit entry. This page covers the syntax, what handler steps can read, the order of events, and the rules the compiler enforces.

Syntax

The complete example is examples/checkout.orbit, with a test in examples/checkout.test.orbit (Testing workflows).

import "contracts.orbit"

workflow Checkout {
    version "1.0.0"
    input { order_id: String, customer_id: String, amount: Float, items: List<LineItem> }

    step reserve {
        worker "inventory.reserve"
        with { order_id: input.order_id, items: input.items }
        compensate {
            worker "inventory.release"
            with { reservation_id: reserve.reservation_id }
        }
    }

    step charge {
        worker "payments.charge"
        after reserve
        with { order_id: input.order_id, amount: input.amount, currency: "USD" }
    }

    on failure {
        step tell_customer {
            worker "notifications.send"
            with {
                customer_id: input.customer_id
                message: "We could not complete order " + input.order_id + ": " + failure.message
            }
        }
        step summary {
            compute { code: failure.code, reserved: !is_null(reserve), charged: !is_null(charge) }
        }
    }

    on cancel {
        step confirm_cancel {
            worker "notifications.send"
            with { customer_id: input.customer_id, message: "Order " + input.order_id + " was cancelled" }
        }
    }
}

A workflow has at most one block of each kind. A block contains step declarations and nothing else.

A successful execution runs no handler. When the matching block is absent, the execution finishes exactly as it would without handlers. A return expression that fails, or a result that does not match output, fails the execution directly, after every step has finished; no handler runs in that case.

What handler steps can read

failure exists only inside handlers; using it elsewhere is error E0401.

Order of events

When the payment above is declined, orbit logs shows compensation first, then the handler, then the terminal event:

+    59ms   #9  StepFailed                step=charge error=CARD_DECLINED charge of 9000.0 USD declined
+    59ms  #10  CompensationStarted       reason=step `charge` failed: charge of 9000.0 USD declined
+    59ms  #11  StepScheduled             step=compensate:reserve attempt=1
+    70ms  #12  StepDispatched            step=compensate:reserve attempt=1 worker_id=orders-typescript
+   150ms  #13  StepSucceeded             step=compensate:reserve attempt=1
+   151ms  #14  CompensationCompleted
+   151ms  #15  HandlersStarted           kind=failure
+   151ms  #16  StepScheduled             step=on_failure:tell_customer attempt=1
+   151ms  #17  StepSucceeded             step=on_failure:summary attempt=1
+   154ms  #18  StepDispatched            step=on_failure:tell_customer attempt=1 worker_id=orders-typescript
+   187ms  #19  StepSucceeded             step=on_failure:tell_customer attempt=1
+   187ms  #20  WorkflowFailed            error=CARD_DECLINED step `charge` failed: charge of 9000.0 USD declined

1. In-flight steps finish, and the steps that succeeded are compensated (newest first). See Compensation.
2. HandlersStarted records the block that runs (kind) and the compensation outcome that the terminal event will carry.
3. Handler steps run in dependency order; steps without a dependency between them run concurrently, as in the main workflow. Their unit keys are on_<kind>:<step>, for example on_failure:tell_customer.
4. When every handler step has finished, the terminal event (WorkflowFailed, WorkflowCancelled or WorkflowTimedOut) is recorded, with the original error and compensation outcome.

When a handler step fails

A handler step can retry like any other (retry { ... }). If it still fails, the failure is recorded on its unit and the steps that depend on it are cancelled, but the execution’s outcome does not change: the terminal event keeps the error that started the shutdown, not the handler’s. Other handler steps still run.

Rules

error[E0307]: `await` is not allowed in an `on failure` step
 --> bad.orbit:6:24
  |
6 |         step x { await s }
  |                        ^
  = note: handlers run while the execution is finishing; it no longer accepts signals

Workflows that declare handlers compile to orbit-ir/2; see Versioning.

See also

• Event handlers
• Compensation
• Retries and timeouts
• Executions and history
• Running the server: resource limits
• Compiler diagnostics
• Testing workflows

Event handlers

An event handler is a block of steps that runs every time a given signal arrives, alongside the workflow’s main steps: on event <signal> { ... }. Use it for messages that can come any number of times while an execution is running, such as tracking scans, progress updates or comments. Use await instead when the workflow has to stop and wait for one specific message. This page covers the syntax, what handler steps can read, how instances run, and the rules the compiler enforces.

Syntax

The complete example is examples/shipment.orbit, with a test in examples/shipment.test.orbit (Testing workflows).

import "contracts.orbit"

workflow Shipment {
    version "1.0.0"
    input { shipment_id: String, customer_id: String }

    signal location { place: String, eta_hours: Int = 0 }
    signal delivered { signed_by: String }

    step arrival { await delivered timeout 30d }

    step confirm {
        worker "notifications.send"
        with {
            customer_id: input.customer_id
            message: "Shipment " + input.shipment_id + " was delivered, signed by " + arrival.signed_by
        }
    }

    on event location {
        step text {
            compute if event.eta_hours > 0
                then "Shipment " + input.shipment_id + " is in " + event.place + ", about " + string(event.eta_hours) + "h away"
                else "Shipment " + input.shipment_id + " is in " + event.place
        }
        step tell {
            worker "notifications.send"
            with { customer_id: input.customer_id, message: text }
        }
    }

    return { signed_by: arrival.signed_by }
}

The signal must be declared with signal. A workflow has at most one on event block per signal, and a block contains step declarations and nothing else. Send the signal as usual:

orbit signal ship-1 location --data '{"place":"Rotterdam","eta_hours":30}'

What handler steps can read

event exists only inside on event blocks; using it elsewhere is error E0401.

How instances run

Each arriving signal starts a new instance of the block. Instances run concurrently with the main steps and with each other, and each has its own copy of every step:

+     0ms   #3  SignalAwaitStarted        step=arrival signal=delivered
+     0ms   #4  SignalReceived            name=location
+     0ms   #5  SignalDelivered           step=on_event:location@4 signal_seq=4
+     0ms   #6  StepSucceeded             step=on_event:location@4:text attempt=1
+     0ms   #7  StepScheduled             step=on_event:location@4:tell attempt=1
+     0ms   #8  StepDispatched            step=on_event:location@4:tell attempt=1 worker_id=simulator
+     0ms   #9  StepSucceeded             step=on_event:location@4:tell attempt=1
+     0ms  #10  SignalReceived            name=location
+     0ms  #11  SignalDelivered           step=on_event:location@10 signal_seq=10
+     0ms  #12  StepSucceeded             step=on_event:location@10:text attempt=1
...
+     0ms  #16  SignalReceived            name=delivered
+     0ms  #17  SignalDelivered           step=arrival signal_seq=16
+     0ms  #20  StepSucceeded             step=confirm attempt=1
+     0ms  #21  WorkflowCompleted

1. SignalReceived records the signal; SignalDelivered starts an instance. The instance key is on_event:<signal>@<seq>, where <seq> is the sequence number of the SignalReceived event, so keys are stable across restarts and replays. The instance unit’s output is the payload.
2. The block’s steps run in dependency order with unit keys on_event:<signal>@<seq>:<step>, for example on_event:location@4:tell. They retry, time out and dispatch to workers like any other step.
3. The execution completes only when the main steps and every started instance are finished. A signal that arrives while instances are still running starts another one.

orbit status lists instance units with the other steps, and orbit inspect shows the block under on event <signal>.

Failures and shutdown

• A step of an instance that fails permanently fails the execution, like a failing main step: steps that have not started (in every instance and in the main workflow) are cancelled, in-flight attempts finish, succeeded steps with a compensate are compensated, and the on failure handler runs.
• When the execution is cancelled, times out or fails, signals that arrive afterwards start no instance. A signal sent to a terminal execution is refused, as for any signal.
• A step with a when that is false is skipped, and steps that read it see null.

Testing

orbit test sends a signal that an on event block handles as soon as the execution is idle, without waiting for an await. In expectations, write the step as on_event:<signal>:<step>. The expectation must hold for every instance of the block, and at least one instance must have started:

test "every scan notifies the customer" {
    workflow Shipment
    input { shipment_id: "S-1", customer_id: "c-1" }
    mock "notifications.send" returns { delivered: true }
    signal location { place: "Rotterdam", eta_hours: 30 }
    signal location { place: "Utrecht" }
    signal delivered { signed_by: "J. de Vries" }
    expect status COMPLETED
    expect step on_event:location:tell SUCCEEDED
}

Rules

error[E0322]: signal `note` is handled by `on event` and cannot also be awaited
 --> aw.orbit:4:20
  |
4 |     step a { await note timeout 1h }
  |                    ^^^^
5 |     on event note {
  |              ---- handled here
  = note: every signal handled by `on event` starts the handler; an `await` would compete for it

Workflows with on event blocks compile to orbit-ir/2; see Versioning.

See also

• Signals and queries
• Outcome handlers
• Compensation
• Testing workflows
• Compiler diagnostics

Continue-as-new

An execution’s history grows with every step it runs. A workflow that loops for a long time, such as a subscription that bills every month or a poller that fetches page after page, would record an unbounded history if it ran inside one execution forever. continue_as_new ends the current run when its steps are done and starts a new run of the same execution, with a new input and an empty history. The execution keeps its id; each run is replayed, held in memory and limited on its own. This page covers the syntax and why it has this form, what happens at the switch, how runs are stored and read, and how it combines with signals, children, limits and tests.

Syntax

continue_as_new is a workflow member, next to return:

continue_as_new [when <condition>] with <input>

When every step of the run has finished (the same point at which return is evaluated), the runtime evaluates the condition. If it is true, or if there is no when, the run ends and the next one starts with <input>; otherwise the run completes with return as usual. when and with may come in either order, and the expression after with may span several lines like any object literal.

examples/subscription.orbit bills a customer once per period, with one run per period:

import "contracts.orbit"

workflow Subscription {
    version "1.0.0"
    description "Charge a customer once per period, for a number of periods"
    input {
        customer_id: String
        amount: Float
        periods: Int = 12
        period: Int = 1
        charged: Float = 0.0
    }
    output { periods: Int, charged: Float }

    // The current period, readable at any time: `orbit query <id> period`.
    query period = { period: input.period, of: input.periods, charged: input.charged }

    step charge {
        worker "payments.charge"
        with {
            order_id: input.customer_id + "-" + string(input.period)
            amount: input.amount
            currency: "USD"
        }
        idempotency_key input.customer_id + "/period-" + string(input.period)
        retry { attempts: 5, backoff: exponential, initial_delay: 1m, max_delay: 1h }
    }

    step receipt {
        worker "notifications.send"
        after charge
        with {
            customer_id: input.customer_id
            message: "Payment " + charge.transaction_id + " for period " + string(input.period)
        }
    }

    step next_period { sleep 30d after receipt }

    // Not the last period: start the next one. `with` is typed against the
    // workflow input (omitted fields take their defaults).
    continue_as_new when input.period < input.periods with {
        customer_id: input.customer_id
        amount: input.amount
        periods: input.periods
        period: input.period + 1
        charged: input.charged + input.amount
    }

    return { periods: input.period, charged: input.charged + input.amount }
}

Type checking

The input after with is checked against the workflow’s own input type, exactly like the input of a worker step against its contract: every required field must be given with the right type, fields with defaults may be left out (the defaults are applied when the run starts), and unknown fields are errors. The expressions can read input, the outputs of the run’s steps (a step that may have been skipped reads as optional) and execution. The condition must be a Bool; null counts as false.

Compiler diagnostics shows the messages. A workflow with continue_as_new compiles to orbit-ir/2; a workflow without it keeps its IR version and its definition hash (Versioning).

Why a declarative member

ORBIT workflows are declarations, not programs: steps and their dependencies are a graph, and the only place a workflow decides what happens after its steps is return. continue_as_new sits at that same place and has the same shape as a step’s when and with, so it reads like the rest of the language and the compiler can check it completely: the next input is typed against the workflow input, and both expressions see the same scope as return. Because it is evaluated only when every step has finished, a run never switches with work in flight: there are no running tasks, timers, children or event handlers to carry over, only the input and the buffered signals. The alternatives were a return continue <expr> form, which would make one member return two kinds of things, and a dedicated step, which could run while other steps were still in flight and would need rules for what happens to them.

What happens at the switch

When the decider finds the condition true, it records WorkflowContinuedAsNew { next_run, input } as the run’s terminal event (the run’s status is CONTINUED_AS_NEW). In the same database transaction, the runtime:

1. appends that event to the finished run,
2. moves the finished run’s history from execution_events to execution_run_events, keyed by execution id and run number,
3. writes the new run’s first events: WorkflowCreated with run, WorkflowStarted, and one SignalReceived per buffered signal (below),
4. points the execution’s row in workflow_executions at the new run.

A crash therefore leaves the execution either in the finished run (which is decided again after recovery, with the same result) or in the new run; never between them. The new run is then advanced like a newly started execution.

The Inbox workflow below takes one message signal per run and stops at stop. Three signals were sent at once, while run 1 was sleeping:

workflow Inbox {
    version "1.0.0"
    input { seen: Int = 0 }
    output { seen: Int }
    signal message { text: String }
    step take { await message timeout 1d }
    step pause { sleep 2s after take }
    continue_as_new when take.text != "stop" with { seen: input.seen + 1 }
    return { seen: input.seen + 1 }
}

$ orbit logs inbox-1 --run 1
+     0ms   #1  WorkflowCreated
+     0ms   #2  WorkflowStarted
+     1ms   #3  SignalAwaitStarted        step=take signal=message
+    10ms   #4  SignalReceived            name=message
+    11ms   #5  SignalDelivered           step=take signal_seq=4
+    11ms   #6  TimerStarted              step=pause
+    20ms   #7  SignalReceived            name=message
+    28ms   #8  SignalReceived            name=message
+    2.1s   #9  TimerFired                step=pause
+    2.1s  #10  WorkflowContinuedAsNew    next_run=2
$ orbit logs inbox-1 --run 2
+     0ms   #1  WorkflowCreated           run=2
+     0ms   #2  WorkflowStarted
+     0ms   #3  SignalReceived            name=message
+     0ms   #4  SignalReceived            name=message
+     2ms   #5  SignalAwaitStarted        step=take signal=message
+     2ms   #6  SignalDelivered           step=take signal_seq=3
+     2ms   #7  TimerStarted              step=pause
+    2.1s   #8  TimerFired                step=pause
+    2.1s   #9  WorkflowContinuedAsNew    next_run=3
$ orbit logs inbox-1 --run 2 --json | head -4
{"seq":1,"timestamp_ms":1794769170400,"type":"WorkflowCreated","workflow":"Inbox","version":"1.0.0","definition_hash":"sha256:066240aa22c4be894c16cd8294f58c93a1d712db065c53d009825221a89cb028","input":{"seen":1},"run":2}
{"seq":2,"timestamp_ms":1794769170400,"type":"WorkflowStarted"}
{"seq":3,"timestamp_ms":1794769170400,"type":"SignalReceived","name":"message","payload":{"text":"second"}}
{"seq":4,"timestamp_ms":1794769170400,"type":"SignalReceived","name":"message","payload":{"text":"stop"}}

Run 1 took first; second and stop were still buffered when it ended, so run 2 starts with both, in arrival order, and its await takes second at once. Run 3 starts with stop and completes:

$ orbit status inbox-1
COMPLETED inbox-1  Inbox@1.0.0
  run: 3 (continue-as-new)
  elapsed: 2.1s

  STEP                         STATUS       ATTEMPT     TIME  DETAIL
  take                         SUCCEEDED          1      0ms
  pause                        SUCCEEDED          1     2.1s

  output: {"seen":3}

Runs

An execution started by a schedule keeps its schedule_id in every run, and the schedule’s overlap policy sees it as running until its final run ends.

Combining it with history limits

--max-history-events (and a workflow’s limits { max_history_events: N }) apply to each run. A workflow that continues as new before a run reaches the limit can run indefinitely under a small limit, and the limit then catches a run that grows unexpectedly. The Inbox execution above recorded 27 events across three runs on a server started with --max-history-events 12; no run recorded more than 10.

workflow Poller {
    version "1.0.0"
    input { cursor: String = "" }
    // A run that reaches 500 events fails with LIMIT_EXCEEDED; each run
    // here records about ten, then continues.
    limits { max_history_events: 500 }
    ...
    continue_as_new when page.has_more with { cursor: page.next }
}

Size a run so that it stays well below the limit: for a for step, each element adds three to five events.

Continue-as-new bounds what one run holds and replays; the archived runs stay in the database (Storage: retention).

Replay and tests

Each run replays on its own against the definition, with its carried signals as external events:

$ orbit replay inbox-1 --run 2
replayed 9 events of inbox-1 against Inbox@1.0.0 with the current decider
  5 decided, 4 external
consistent: every recorded decision is reproduced

orbit test and orbit simulate follow every run. Expectations are checked against the final run, and expect runs N checks how many runs there were (Testing workflows):

test "three periods are three runs" {
    workflow Subscription
    input { customer_id: "c-1", amount: 9.5, periods: 3 }
    mock "payments.charge" returns { transaction_id: "tx-" + input.order_id, status: "captured" }
    mock "notifications.send" returns { delivered: true }
    expect status COMPLETED
    expect runs 3
    expect output { periods: 3, charged: 28.5 }
}

Limitations

• The switch happens only when every step has finished. There is no way to continue as new from inside a step, a handler or an on event block.
• A failure while evaluating the condition or the input (for example a division by zero) fails the run with EXPRESSION_ERROR; an input that does not match the workflow’s input type at run time fails it with INPUT_CONTRACT_VIOLATION. Neither starts a new run.
• A workflow whose run finishes immediately (for example, only compute steps) and always continues starts a new run on every runtime tick. Give such a loop a sleep or an await.
• GET /v1/executions/{id} does not list the earlier runs; the latest run’s run number tells how many there are.

See also

• Executions and history: runs
• Signals and queries
• Running the server: resource limits
• Schedules
• Web UI: runs
• Workflow graphs, documentation and process diffs show continue_as_new
• HTTP API: history
• Testing workflows

Expressions

Expressions compute step inputs, conditions, idempotency keys, fan-out lists and workflow results from the workflow input and the outputs of earlier steps. They are pure and deterministic: they perform no I/O and cannot read the clock, so every decision the runtime makes can be replayed from the execution history. This page is the reference for literals, references, operators, precedence and the evaluation rules, including the behavior with null.

Where expressions appear

Literals

Notes:

• Strings are single-line. The escapes are \n, \t, \r, \", \\ and \u{X...} with one or more hexadecimal digits. Any other escape is E0004, and a line break inside a string is E0002.
• Underscores in numbers are ignored (1_000 is 1000).
• A float needs digits on both sides of the point: 0.5, not .5 or 5.. There is no exponent notation.
• A leading - is an operator. -5 is folded into a negative literal. Because the literal 9223372036854775808 does not fit in 64 bits, write the minimum Int as -9223372036854775807 - 1.
• A number directly followed by letters is a duration; an unknown unit is E0005 (5q).

References

An identifier at the start of an expression is a reference. It resolves, in order, to:

1. a loop variable bound by the enclosing for step,
2. input, the workflow input,
3. execution, the execution metadata,
4. a step of the workflow.

Anything else is E0401, with a suggestion when a name is close.

execution must be followed by exactly one of id, workflow or version. execution alone, or another field, is E0402.

The type of a step reference depends on the step: optional if the step has a when, a list if it has a for. See Steps.

Member access

a.b reads field b of a record. An unknown field is E0402, with the closest field suggested or the available fields listed.

Member access propagates null: if a is null, a.b is null. The type of a.b is therefore optional whenever a is optional, which is how a skipped step’s fields become optional.

Member access also works on maps, as a shorthand for indexing with a string: headers.accept is headers["accept"], and its type is optional because the key may be missing.

Indexing

target[index] reads an element:

A field access after an index or a call reads a field of the result: input.items[0].sku has type String?.

Object literals

workflow Objects {
    version "1.0.0"
    input { order_id: String, amount: Float }
    return {
        id: input.order_id
        "content-type": "application/json"
        totals: { net: input.amount, gross: input.amount * 1.2 }
    }
}

• Keys are identifiers or string literals. Use a string for keys that are not identifiers, such as "content-type", or for true, false and null.
• A key may appear only once (E0107).
• Entries are separated by commas, semicolons or line breaks.
• There is no shorthand: { order_id } is a syntax error; write { order_id: input.order_id }.

How an object literal is typed depends on where it appears:

List literals

Items are separated by commas or line breaks; a trailing comma is allowed. A semicolon between items is a syntax error. The item type is the combination of all item types (see Types), [] has type List<JSON>, and incompatible items are E0400. Where a List<T> is expected, each item is checked against T.

Operators

From lowest to highest precedence. All binary operators are left-associative.

1 + 2 * 3 == 7 && !false therefore groups as ((1 + (2 * 3)) == 7) && (!false), and 10 - 3 - 2 is (10 - 3) - 2. Use parentheses to group differently.

Operators that are not defined for their operand types are E0406, with labels showing each operand’s type. Optional operands are not accepted by arithmetic, comparison or logical operators; the diagnostic suggests coalesce. If either operand has type JSON, the check is skipped and the operation is checked at runtime.

Arithmetic

• / on integers truncates toward zero: 7 / 2 is 3 and -7 / 2 is -3.
• % takes the sign of the dividend: -7 % 3 is -1.
• Division or remainder by zero, integer or float, is an error.
• A float result that is not finite becomes null.
• Duration has no arithmetic: 30s + 1s is E0406.

The runtime chooses integer or float arithmetic from the actual JSON values, not from the declared types. A Float field whose JSON value is a whole number written without a decimal point, such as 5, is an integer at runtime, and input.price / 2 then performs integer division (2). Write a float literal (input.price / 2.0) or convert explicitly (float(input.price) / 2) when you need float division.

Concatenation

+ on two strings concatenates them. + on two lists returns the items of the left list followed by the items of the right list; the result type is the combination of both list types. A string and a non-string is E0406, and the diagnostic suggests string:

workflow Label {
    version "1.0.0"
    input { order_id: String, attempt: Int }
    return { label: "order-" + input.order_id + "-" + string(input.attempt) }
}

Comparison

<, <=, > and >= compare two numbers (Int and Float mix freely) or two strings. Strings compare lexicographically by Unicode code point, so "B" < "a" is true. Other types, including optional operands and Duration, are E0406.

Equality

== and != compare values structurally: lists element by element, records and maps key by key. Numbers compare by value, so 1 == 1.0 is true.

The operands must have compatible types: comparing an Int with a String is E0406 (“values of different types are never equal”). Comparing any value with null is allowed, which is how you test an optional value:

return { charged: charge.transaction_id != null }

Logical operators

&& and || take Bool operands and short-circuit: the right operand is not evaluated when the left one decides the result. ! negates a Bool. A Bool? operand is rejected at compile time (E0406 for &&/||, E0405 for !); use coalesce(flag, false). At runtime, a non-boolean operand (possible only through JSON) is an error.

Conditional expressions

workflow Route {
    version "1.0.0"
    input { score: Float }
    return {
        queue: if input.score > 0.8 then "manual" else "auto"
    }
}

if c then a else b evaluates c, then exactly one branch.

• The condition must be Bool or Bool? (E0408). A null condition selects the else branch.
• else is required.
• The result type combines both branch types: if c then 1 else 2.5 is Float, and if c then "x" else null is String?. Incompatible branches are E0400.
• if, then and else may be on separate lines.

Function calls

name(arg, ...) calls a built-in function. There are no user-defined functions. An unknown function or a wrong number of arguments is E0407. The opening parenthesis must be on the same line as the name.

Lambdas

A lambda is a one-parameter function, written parameter => body:

workflow Prices {
    version "1.0.0"
    input { items: List<{ sku: String, price: Float, quantity: Int }> }
    return {
        totals: map(input.items, item => item.price * float(item.quantity))
        expensive: filter(input.items, item => item.price > 100.0)
        all_in_stock: all(input.items, item => item.quantity > 0)
    }
}

workflow Totals {
    version "1.0.0"
    input { prices: List<Float> }
    step total {
        compute { doubled: p => p * 2.0 }
    }
}

error[E0415]: a lambda can only be passed to `map`, `filter`, `any`, `all` or `find`
 --> lambda.orbit:5:28
  |
5 |         compute { doubled: p => p * 2.0 }
  |                            ^^^^^^^^^^^^
  = help: for example `map(input.items, item => item.price)`

error: compilation failed: 1 error(s), 0 warning(s)

A workflow that contains a lambda anywhere compiles to orbit-ir/2. See Versioning.

Line breaks and operators

An infix operator, and a postfix ., [ or (, must be on the same line as its left operand. A line break before one of these tokens ends the expression. This is what lets object literals and blocks use line breaks as separators:

workflow Lines {
    version "1.0.0"
    input { a: Int, b: Int }
    return {
        sum: input.a +
            input.b          // continues: `+` ends the previous line
        a: input.a
        b: -input.b          // a new entry, not `input.a - input.b`
    }
}

Starting a line with an operator does not continue the previous line:

workflow Broken {
    version "1.0.0"
    input { a: Int, b: Int }
    return {
        sum: input.a
            + input.b
    }
}

error[E0100]: expected a field name or `}`, found `+`
 --> broken.orbit:6:13
  |
6 |             + input.b
  |             ^

error[E0102]: unexpected `+` in workflow
 --> broken.orbit:6:13
  |
6 |             + input.b
  |             ^

error[E0104]: expected a declaration, found `}`
 --> broken.orbit:8:1
  |
8 | }
  | ^
  = note: top-level declarations are `workflow`, `schema`, `task`, `import` and `test`

error: compilation failed: 3 error(s), 0 warning(s)

The first error is the real one; the others follow from the parser recovering. Put the operator at the end of the line instead. Parentheses do not change this rule: inside ( ... ) an operator must also follow its left operand on the same line.

Runtime errors

Type checking prevents most errors, but some can only happen at runtime: integer overflow, division by zero, a failed conversion such as int("abc"), or an operation on a JSON value of the wrong shape. An error while evaluating:

• a step’s with, when, for, idempotency_key or compute expression fails that step with the non-retryable code EXPRESSION_ERROR, which aborts the workflow and starts compensation,
• the workflow return fails the workflow with EXPRESSION_ERROR, without compensation,
• a query fails only that request, with 422 QUERY_FAILED; the execution is not affected.

The error message names the expression and the cause, for example evaluating input: division by zero.

See also

• Built-in functions
• Compute steps
• Types
• Conditions
• Grammar

Built-in functions

ORBIT provides a fixed set of pure functions for mapping data between steps: null handling, conversions, string and collection helpers, numeric helpers, and collection functions that take a lambda. Like all expressions, they are deterministic and perform no I/O. This page lists every function with its signature, argument and result types, behavior with null, runtime errors, and examples.

Summary

General rules:

• Function names are case-sensitive, and there are no user-defined functions.
• An unknown name or a wrong number of arguments is E0407. The diagnostic suggests a close name or prints the signature.
• An argument of the wrong type is E0400 (argument 1 of `len` must be a String, List or Map, found `Int` ).
• Arguments of type JSON are accepted everywhere and checked at runtime.
• A runtime error, such as int("abc"), fails the step being scheduled (or the workflow, in return) with EXPRESSION_ERROR. See Expressions.

coalesce

coalesce(a: T?, b: T?, ..., z: T) -> T

Returns the first argument that is not null, or null if all are null. Takes one or more arguments.

workflow Coalesce {
    version "1.0.0"
    input { nickname: String?, name: String?, discount: Float? }
    return {
        display: coalesce(input.nickname, input.name, "customer")   // String
        maybe: coalesce(input.nickname, input.name)                 // String?
        discount: coalesce(input.discount, 0)                       // Float
    }
}

coalesce is the standard way to turn an optional value, such as a field of a skipped step, into a required one. See Conditions.

is_null

is_null(x: T) -> Bool

Returns true if x is null. Accepts any type. is_null(x) is equivalent to x == null.

workflow IsNull {
    version "1.0.0"
    input { coupon: String? }
    return { has_coupon: !is_null(input.coupon) }
}

len

len(x: String | List<T> | Map<String, T>) -> Int

Optional arguments are accepted, and null counts as empty. Other types are E0400.

workflow Len {
    version "1.0.0"
    input { items: List<LineItem>, note: String? }
    return { item_count: len(input.items), note_length: len(input.note) }
}

string

string(x: T) -> String

Converts any value to a string:

workflow ToString {
    version "1.0.0"
    input { order_id: String, attempt: Int }
    return { key: input.order_id + "#" + string(input.attempt) }
}

int

int(x: Int | Float | String | Bool) -> Int

The compiler accepts optional arguments, but a null value fails at runtime. Use int(coalesce(x, 0)) when the argument may be null.

float

float(x: Int | Float | String | Bool) -> Float

Use float to force float arithmetic on a value that may arrive as a JSON integer: float(input.price) / 2. See Arithmetic.

Before ORBIT 0.2, the compiler accepted a Bool argument but the runtime rejected it with EXPRESSION_ERROR.

contains

contains(haystack: String, needle: String) -> Bool
contains(haystack: List<T>, needle: T) -> Bool
contains(haystack: Map<String, T>, key: String) -> Bool

The compiler checks only the number of arguments (2), not their types. A combination outside the table, such as a string haystack with a number needle, is a runtime error.

workflow Contains {
    version "1.0.0"
    input { tags: List<String>, email: String }
    return {
        vip: contains(input.tags, "vip")
        corporate: contains(lower(input.email), "@example.com")
    }
}

lower, upper, trim

lower(s: String) -> String
upper(s: String) -> String
trim(s: String) -> String

With a String? argument the result is String?, and null returns null. Other argument types are E0400.

workflow Normalize {
    version "1.0.0"
    input { email: String, nickname: String? }
    return {
        email: lower(trim(input.email))          // String
        nickname: upper(input.nickname)          // String?
    }
}

join

join(items: List<T>, separator: String) -> String

Concatenates the items, with separator between them. String items are used as they are; other items are converted to their JSON form, as with string: join([1, 2], ",") is "1,2". An empty list gives "".

The compiler accepts an optional list, but a null list is a runtime error.

workflow Join {
    version "1.0.0"
    input { skus: List<String> }
    return { summary: join(input.skus, ", ") }
}

keys

keys(m: Map<String, T>) -> List<String>

Returns the keys of a map (or the field names of a record), in the order they appear in the JSON object. A null argument is a runtime error.

workflow Keys {
    version "1.0.0"
    input { labels: Map<String, String> }
    return { label_names: keys(input.labels) }
}

min, max

min(a: number, b: number, ...) -> number
max(a: number, b: number, ...) -> number

Return the smallest or largest argument. Take one or more arguments, each Int or Float (or JSON). Optional arguments are E0400; wrap them in coalesce.

workflow Clamp {
    version "1.0.0"
    input { requested: Int }
    return { batch_size: max(1, min(input.requested, 500)) }
}

abs

abs(x: Int) -> Int
abs(x: Float) -> Float

Returns the absolute value. The result type is the argument type. An optional argument is E0400. abs of the minimum Int overflows and is a runtime error.

workflow Abs {
    version "1.0.0"
    input { expected: Float, actual: Float }
    return { drift: abs(input.actual - input.expected) }
}

sum

sum(list: List<Int>) -> Int
sum(list: List<Float>) -> Float

Adds the elements of a list of numbers. The result is Int for a List<Int> and Float otherwise. The list may be optional; sum of null and of an empty list is 0. An element that is not a number is a runtime error (possible only with JSON values), and so is Int overflow. Any other argument type is E0400 (argument 1 of `sum` must be a List of Int or Float, found `List<String>` ).

At runtime, the result is an integer whenever every element is an integer JSON number, so the sum of an empty List<Float> is the JSON number 0, not 0.0. JSON consumers that distinguish the two should not rely on the representation.

workflow Invoice {
    version "1.0.0"
    input { quantities: List<Int>, prices: List<Float> }
    return { units: sum(input.quantities), total: sum(input.prices) }
}

Collection functions

map, filter, find, any and all take a list and a lambda: a one-parameter function written parameter => expression. The function calls the lambda once per element, in list order, with the parameter bound to the element. See Expressions for the lambda syntax.

Rules shared by all five:

• They take exactly two arguments (E0407 otherwise, with the signature in a note). The first must be a list (E0400: argument 1 of `map` must be a List, found `String` ); a List<T>? is accepted, and null behaves like an empty list. The second must be a lambda (E0400: argument 2 of `any` must be a lambda).
• The lambda body can read input, execution, step outputs, loop variables and the parameters of enclosing lambdas. Reading a step’s output adds a dependency, as anywhere else.
• For filter, find, any and all, the body must have type Bool (E0400, or E0405 for a Bool?). At runtime a null condition counts as false.
• The parameter must not reuse the name of a step, a loop variable, an enclosing lambda parameter, input or execution (E0413).
• A lambda anywhere else is E0415.
• An error inside the body, such as a division by zero for one element, fails the whole call.

map

map(list: List<T>, f: T => U) -> List<U>

Returns the list of f(x) for each element x.

workflow Emails {
    version "1.0.0"
    input { users: List<{ email: String, name: String }> }
    return { emails: map(input.users, u => lower(u.email)) }
}

filter

filter(list: List<T>, f: T => Bool) -> List<T>

Returns the elements for which f is true, in their original order.

workflow Restock {
    version "1.0.0"
    input { items: List<{ sku: String, stock: Int }> }
    return { low: map(filter(input.items, i => i.stock < 5), i => i.sku) }
}

find

find(list: List<T>, f: T => Bool) -> T?

Returns the first element for which f is true, or null when there is none. The result is always optional.

workflow Primary {
    version "1.0.0"
    input { addresses: List<{ city: String, primary: Bool }> }
    return { city: coalesce(find(input.addresses, a => a.primary).city, "unknown") }
}

any, all

any(list: List<T>, f: T => Bool) -> Bool
all(list: List<T>, f: T => Bool) -> Bool

any is true when f is true for at least one element, and all when it is true for every element. Both stop at the first element that decides the result. For an empty list, any is false and all is true.

task "mail.send" {
    input { to: List<String> }
    output { sent: Int }
}

workflow Notify {
    version "1.0.0"
    input { users: List<{ email: String, active: Bool }> }

    step send {
        worker "mail.send"
        when any(input.users, u => u.active)
        with { to: map(filter(input.users, u => u.active), u => u.email) }
    }
}

A workflow that uses a lambda anywhere compiles to orbit-ir/2. See Versioning.

See also

• Expressions
• Compute steps
• Types
• Conditions

HTTP adapter

orbit.http.request is a built-in task that calls an HTTP endpoint from the runtime itself, without a worker. Use it for webhooks, health checks and simple API calls that need no business logic. This page covers the task’s contract, how requests are built, how responses and errors are mapped, and how to enable the adapter on the server.

Enabling the adapter

The adapter lets workflow authors make outbound requests from the runtime host, so it is disabled by default. Start the server with --enable-http-adapter:

orbit server --enable-http-adapter

On a server without the flag, every orbit.http.request attempt fails with ADAPTER_DISABLED, which is not retryable. Workflows that use the adapter still compile and register. See Running the server and Security.

Contract

The task is declared in the prelude that every compilation includes:

task "orbit.http.request" {
    version "1.0.0"
    input {
        method: String = "GET"
        url: String
        headers: Map<String, String> = {}
        body: JSON = null
    }
    output {
        status: Int
        headers: Map<String, String>
        body: JSON
    }
}

Example

workflow NotifyWebhook {
    version "1.0.0"
    input { order_id: String, url: String }

    step deliver {
        worker "orbit.http.request"
        with {
            method: "POST"
            url: input.url
            headers: { "content-type": "application/json", "x-order-id": input.order_id }
            body: { event: "order.completed", order_id: input.order_id }
        }
        timeout 10s
        retry { attempts: 5, backoff: exponential, initial_delay: 1s, max_delay: 30s }
    }

    return { delivered: deliver.status < 300, status: deliver.status }
}

deliver.status is an Int, deliver.headers["content-type"] is a String?, and deliver.body is JSON, so its fields can be read without type errors (deliver.body.id) and are checked at runtime.

Request body encoding

For POST, PUT and PATCH:

For GET, HEAD, OPTIONS and DELETE, body is ignored.

Status codes and errors

A 404 or 400 is a successful step: the workflow decides what it means. To treat those as failures, branch on status or check it in a later step. Retryable failures are retried only if the step has a retry policy with more than one attempt; see Retries and timeouts.

Timeouts and limits