Concepts on Orchard

Scenarios

Mon, 01 Jan 0001 00:00:00 +0000

Scenarios#

A scenario is the top-level entrypoint in Orchard. It is the thing a user runs. A scenario declares the providers it needs, accepts parameters via variables, composes components and actions, and exposes outputs.

scenario "merchant_with_chargeback" {
 required_providers {
 postgres = { source = "builtin/postgres" }
 }

 variable "dsn" {}
 variable "merchant_name" {
 default = "Acme Corp"
 }

 provider "postgres" {
 dsn = var.dsn
 }

 component "merchant" "base" {
 source = "../components/merchant.hcl"
 inputs = { name = var.merchant_name }
 }

 output "merchant_id" {
 value = component.merchant.base.id
 }
}

What goes inside a scenario#

A scenario file contains exactly one scenario "<name>" { ... } block. Inside that block, you can declare:

Components

Mon, 01 Jan 0001 00:00:00 +0000

Components#

A component is a reusable unit of state. It’s the Orchard equivalent of a function: it takes inputs, performs some work, and returns outputs. Scenarios compose components to describe complex state without repeating themselves.

Defining a component#

A component lives in its own file. The file contains one component "<name>" { ... } block:

# components/merchant.hcl
component "merchant" {
 variable "name" {
 default = "Default Merchant"
 }

 variable "region" {
 default = "us"
 }

 action "postgres_query" "create" {
 query = "INSERT INTO merchants (name, region) VALUES ('${var.name}', '${var.region}') RETURNING id, name, region"
 }

 output "id" { value = action.postgres_query.create.id }
 output "name" { value = action.postgres_query.create.name }
 output "region" { value = action.postgres_query.create.region }
}

A component has the same vocabulary as a scenario — variables, actions, outputs — but no required_providers or provider blocks. Components inherit their providers from the enclosing scenario.

Providers

Mon, 01 Jan 0001 00:00:00 +0000

Providers#

A provider is the runtime that turns a declarative HCL action into a real side effect. builtin/postgres opens a connection and runs SQL. builtin/http makes HTTP requests. builtin/exec spawns child processes. Custom providers can do anything you can write a binary for.

The two kinds of providers#

Built-in providers are compiled into the orchard binary. They’re always available and need no installation. Today that’s:

builtin/postgres
builtin/http
builtin/exec

External providers are separate binaries that speak Orchard’s provider protocol over stdio. They’re referenced by path:

Wiring

Mon, 01 Jan 0001 00:00:00 +0000

Wiring#

Wiring is how outputs from one step flow into the inputs of the next, and how Orchard decides the order to execute steps in. You never write a graph by hand — you write references in expressions, and Orchard derives the graph from them.

References#

Four reference namespaces are in scope inside expressions:

Form	Resolves to	Available when
`var.<name>`	A scenario or component variable.	Plan time — variables are resolved up front.
`action.<type>.<name>.<output>`	An output from another action.	After that action completes.
`component.<type>.<name>.<output>`	An output from a component instance.	After that component resolves.
`var.<name>` (inside a component)	The component’s own variable.	As soon as the component runs.

References can appear inside any attribute expression — in action bodies, provider configs (variables only), output values, or component inputs.

Plan vs run

Mon, 01 Jan 0001 00:00:00 +0000

Plan vs run#

Orchard has two execution modes. They share parsing, validation, and graph construction but diverge on how they deal with providers and side effects.

`orchard plan`#

orchard plan is a read-only preview. It:

Parses the scenario file and any component files it references.
Loads provider schemas.
Validates the scenario: every reference resolves, every required attribute is set, every type matches.
Builds and sorts the dependency graph.
Prints the plan — what will run, in what order, with what inputs.

plan never configures a provider and never executes an action. It cannot open database connections, make HTTP requests, or spawn subprocesses. For built-in providers, plan skips Configure entirely. For external providers, plan uses a short-lived schema probe that runs <binary> schema, reads the schema JSON, and exits immediately.

Lifecycle and teardown

Mon, 01 Jan 0001 00:00:00 +0000

Lifecycle and teardown#

Orchard creates state. Good tools also clean it up. Every orchard run writes a run record describing what happened; orchard teardown uses that record to reverse it.

Run records#

After every orchard run, Orchard writes a JSON file named orchard_<scenario>_run_<id>.json into the current directory. The filename’s <id> prefix is sortable — YYYYMMDDTHHMMSSZ_<8hex> — so listing the directory in your shell gives you runs in chronological order.

$ orchard run scenarios/dev.hcl
scenario: dev
executing...
 ok action.postgres_query.create_merchant (4ms)
 ok action.postgres_query.create_product (2ms)
...

$ ls orchard_dev_run_*.json
orchard_dev_run_20260415T103045Z_a3f29e5b.json

The record captures:

Concepts on Orchard

Scenarios

Scenarios#

What goes inside a scenario#

Components

Components#

Defining a component#

Providers

Providers#

The two kinds of providers#

Wiring

Wiring#

References#

Plan vs run

Plan vs run#

orchard plan#

Lifecycle and teardown

Lifecycle and teardown#

Run records#

`orchard plan`#