Skip to content
The graph

How vect builds the graph

Everything vect does, from validate to apply, starts from one data structure: a single dependency graph. This guide explains how that graph is built from the blocks you write, what creates an edge, what doesn’t, and how you can look at the graph before anything runs. It assumes you’ve finished the First steps tutorial. The normative rules live in the language and compilation specs; we link the requirement IDs where they help.

We’ll use two small example projects. The first is a “fleet”: a shared core stack, one region stack per region, and an audit root that reads from all of them. Every root in it uses the built-in terraform_data resource, so it needs no cloud account.

main.hcl
data "value" "regions" {
  value = {
    use1 = "us-east-1"
    euw1 = "eu-west-1"
  }
}

stack "core" {
  source = "./stacks/core"
}

stack "region" {
  for_each   = data.value.regions.value
  source     = "./stacks/region"
  region     = each.value
  network_id = stack.core.network_id
}

executor "terraform" "audit" {
  source = "./roots/audit"
  inputs = {
    endpoints = [for r in stack.region : r.endpoint]
  }
}

The core stack wraps one Terraform root and exports its network_id. The region stack takes a region and a network_id, wraps an app root, and exports its endpoint. The files are in the example project.

One graph, not one per stack

A vect project is a tree: a root stack, stack blocks that load child folders, and inside each of those, executor and data blocks. It would be natural to build a graph per stack and wire them together. vect doesn’t. It expands the whole tree, every instance of every block in every stack, into one flattened graph, and every ordering decision is made on that graph.

vect graph
data.value.regions
stack.core.terraform.core
stack.core.output.network_id
stack.region["euw1"].var.network_id
stack.region["euw1"].var.region
stack.region["euw1"].terraform.app
stack.region["euw1"].output.endpoint
stack.region["use1"].var.network_id
stack.region["use1"].var.region
stack.region["use1"].terraform.app
stack.region["use1"].output.endpoint
terraform.audit

Read that as an order of evaluation: every node appears after everything it depends on. Notice what’s in the list. Besides the Terraform roots (terraform.audit, stack.core.terraform.core, and so on) and the data source, the graph holds a node for every var a stack receives and every output it exposes. Those nodes are how a value crosses a stack boundary, and they’re why an edge can run from stack.region["use1"].terraform.app up to stack.core.terraform.core without either stack knowing about the other. A stack is a scope (what names a block can see), not a unit of execution. Execution is the graph. Stack scoping rules are covered in Stacks and projects.

Coming from Terraform: a Terraform module is a namespace inside one root, and the plan is one graph per root. Roots can’t see each other, so you reach for terraform_remote_state, a pipeline stage, or a glue script to order them. In vect the unit you run is the whole project, and a Terraform root is just one kind of node in the graph. Cross-root ordering is the same mechanism as in-root ordering: a reference.

References create edges

You never write an edge. You write a reference, and vect finds it. When an expression mentions another block, vect adds an edge from the block that mentions it to the block it names. Four reference forms cover most of what you’ll use (LANG-REF-1):

ReferenceNames
terraform.pet.namethe output name of the terraform executor pet (no executor. prefix)
data.value.regions.valuethe output value of a data block
stack.core.network_idan output of a stack call
var.region, local.xa value in the current stack’s scope

What a reference returns is the output of the block, never its configuration. terraform.pet.name is a Terraform output; source and inputs aren’t visible to anyone else (LANG-REF-2). A reference to something that isn’t declared, or to an output a type doesn’t have, is a diagnostic with a source range, caught by validate.

Edges also follow values through var and output nodes. In the fleet, terraform.app in a region stack reads var.network_id, which the root fills from stack.core.network_id, which is core’s output, which reads terraform.core.network_id. That chain is four references in three files, and you didn’t annotate any of it.

audit shows the other useful property. Its endpoints input is a for expression over stack.region, the whole set of region instances, so it depends on every one of them, however many for_each produces. If you add a region, audit waits for it too.

Two kinds of dependency

vect keeps two lists for every node. The value dependencies are the nodes whose values its expressions use. The dependencies are all of those plus any ordering-only edges (COMP-DEPS-1). Most of the time they’re the same list. They differ when you use depends_on.

depends_on: order without a value

Sometimes one thing has to happen before another and no value connects them: a database must exist before a migration runs, but the migration never reads anything from it. That’s what depends_on is for. The second example project shows it, along with two other meta-arguments we’ll get to:

main.hcl
data "value" "flags" {
  value = {
    canary = false
  }
}

executor "terraform" "migrate" {
  source     = "./roots/migrate"
  depends_on = [terraform.db]
  timeout    = "10m"
}

executor "terraform" "db" {
  source = "./roots/db"
}

executor "terraform" "canary" {
  source  = "./roots/canary"
  enabled = data.value.flags.value.canary
}

migrate is declared before db, which doesn’t matter. The depends_on entry makes db run first:

vect graph
terraform.db
terraform.migrate
data.value.flags

depends_on accepts references to executors, stack calls and their outputs, data and ephemeral blocks, var.*, and local.*; anything else is a diagnostic (LANG-REF-6). When you name a stack call, a var, or a local, vect traces it back through the variable and output nodes to the executors and data blocks behind it, and orders after those (COMP-DEPS-2). So depends_on = [stack.core] means “after everything core’s outputs come from.”

The distinction between the two lists matters at run time. An ordering-only edge never makes one node read another’s value, and it never pulls a node into a targeted run just to supply a value (COMP-DEPS-4). We can see that with a real run (we leave out the engine’s own lines, the ones that start with a node address and |). Targeting migrate alone, with nothing in Inventory yet, works, because it has no value dependency on db:

vect plan --target terraform.migrate
terraform.migrate: running
terraform.migrate: planned will run
plan of workspace "dev": succeeded (run 01a1e26a-a31c-7704-bb6a-18f93f8dac54)
scope: --target terraform.migrate (upstream: inventory)
  terraform.migrate  run  will run

Add --upstream=include and the scope grows to include what migrate must come after:

vect plan --target terraform.migrate --upstream=include
terraform.db: running
terraform.db: planned will run
terraform.migrate: running
terraform.migrate: planned will run
plan of workspace "dev": succeeded (run 01a1e26a-bc33-79bc-a0d8-946877dd5d63)
scope: --target terraform.migrate (upstream: include)
  terraform.db       run  will run
  terraform.migrate  run  will run

(Yours will differ in the run ID. These runs used a local Temporal development server; see Part 3 for the setup.) Compare that with a node that reads a value: in the fleet, targeting a region before core has been applied fails at admission, telling you to apply the upstream first or use --upstream=include, because a region’s input needs core’s actual output.

Planning the whole fleet before anything has been applied shows the same idea from the other side. Only core can be planned for real; the nodes that read its output are deferred:

  stack.core.terraform.core           run    will run
  stack.region["euw1"].terraform.app  defer  unknown inputs: inputs.network_id
  stack.region["use1"].terraform.app  defer  unknown inputs: inputs.network_id
  terraform.audit                     defer  unknown inputs: inputs.endpoints

A region’s network_id is core’s output, which doesn’t exist until core is applied, so vect can’t plan the region yet. It isn’t an error. The edge is still there, and the node is planned during apply, once core’s output is known.

There’s one more source of ordering-only edges, capabilities (provides_execution and requires_execution), which decide where work runs as well as when. They’re covered with the runtime.

Coming from Terraform: depends_on in Terraform orders resources inside one root. Here it orders whole roots, and a stack’s worth of them, across the project. Prefer a reference when you can: a reference carries a value and documents why the order exists. Reach for depends_on when the dependency is real but invisible.

Cycles and unknowns are caught before a run

Because the graph exists before anything runs, a cycle is a compile-time error rather than a deadlock. Two roots that read each other, for example these two executors (the roots are the db and migrate roots from the second example):

main.hcl
executor "terraform" "db" {
  source = "./roots/db"
  inputs = { x = terraform.migrate.y }
}

executor "terraform" "migrate" {
  source = "./roots/migrate"
  inputs = { y = terraform.db.x }
}

fail with the nodes named:

Error: Dependency cycle

  on main.hcl line 1, in executor "terraform" "db":
   1: executor "terraform" "db" {

These declarations are in a dependency cycle, or wait on one, so none of them can be evaluated
first: [terraform.db terraform.migrate].

Anything that decides the shape of the graph has to be known before the graph runs, and that rule is the next section’s subject.

The graph’s shape is decided at plan time

The graph has a fixed set of nodes by the time execution begins. That works because the values that decide the shape (enabled, count, for_each, source, and the capability names) are plan-time known: they can use literals, globals, static vars and locals, and plan-time data blocks, but never an executor’s output (COMP-PLANTIME-1). An executor’s output doesn’t exist until the executor runs, so it can’t decide whether a node exists. If you try:

main.hcl
executor "terraform" "db" {
  source = "./roots/db"
}

executor "terraform" "migrate" {
  source  = "./roots/migrate"
  enabled = terraform.db.ready
}

compilation stops with an error that names the problem:

Error: Invalid enabled

  on main.hcl line 7, in executor "terraform" "migrate":
   7:   enabled = terraform.db.ready

enabled is a plan-time value (COMP-PLANTIME-1), but it references terraform.db, whose result exists
only after it runs.

A data block is plan-time when everything it reads is plan-time, and DAG-deferred otherwise: it becomes a node that runs in the graph, and its outputs are unknown until it does (COMP-PLANTIME-3). In the examples, data "value" is plan-time, so the regions it yields can drive a for_each.

Keyed instances

count and for_each work on stack, executor, data, and ephemeral blocks. They expand at plan time into keyed instances, one node each, addressed with the key: [0] for count, ["use1"] for for_each (LANG-ADDR-5). The fleet’s for_each over a map gave us stack.region["use1"] and stack.region["euw1"], each with its own copy of every node inside the stack. count and for_each on one block are a diagnostic.

Expanding a stack expands everything in it. The terraform.app inside region is a separate executor instance per region, with its own Inventory record, its own state, and its own place in the graph. That’s the model for “the same infrastructure in N places.”

Because the key set comes from plan-time values, changing those values changes the graph. We can show that without touching the configuration, by injecting a different data value from a fact file. A fact file (Part 2) replaces a block’s value for one command:

apac.facts.hcl
data "data.value.regions" {
  value = {
    value = {
      use1  = "us-east-1"
      euw1  = "eu-west-1"
      apse2 = "ap-southeast-2"
    }
  }
}
vect graph --facts apac.facts.hcl
data.value.regions
stack.core.terraform.core
stack.core.output.network_id
stack.region["apse2"].var.network_id
stack.region["apse2"].var.region
stack.region["apse2"].terraform.app
stack.region["apse2"].output.endpoint
stack.region["euw1"].var.network_id
…
terraform.audit

(We trimmed the middle; the use1 and euw1 blocks are as before.) A third region’s worth of nodes appeared, and terraform.audit still comes last. The injected value is wrapped in value = { value = ... } because the outer value is the fact file’s own attribute and the inner one is the value output of data "value".

Coming from Terraform: for_each on a Terraform module is limited to values known at plan, and the plan is per root. Here the same rule applies across the whole project, so a region list can fan out stacks, and every node, in every stack, and everything downstream of them. The cost is the plan-time restriction above; you get a diagnostic naming the unknown input, and offline commands tell you to supply --workspace or --facts to resolve it.

enabled

enabled is a boolean meta-argument, default true, on every block kind that can have instances. It’s the switch for conditionally including a block (Terraform’s count = var.x ? 1 : 0 idiom). A disabled block produces no node that runs, is never read or opened, and evaluates to a typed null (COMP-ENABLED-1). vect graph leaves it out. In the second example, canary is disabled and isn’t in the ordering above. vect inspect --all shows the node and why:

node "terraform.canary" {
  depends_on = ["data.value.flags"]
  enabled    = false
  type       = dynamic
  value      = null
}

A disabled stack disables everything inside it, and each of its outputs becomes a typed null. If a disabled block has an Inventory record from an earlier run, it becomes an orphan and is destroyed on the next apply; that’s covered with the runtime.

Looking at the graph before it runs

Two commands show you the graph, and neither needs a Temporal server or credentials, as long as you don’t pass --workspace.

  • vect graph prints the order. It’s the quick check that an edge exists: if a should wait for b and b isn’t listed first, there’s a missing reference.
  • vect inspect prints every node’s evaluated input and, in depends_on, its dependencies. Anything that depends on a value that doesn’t exist yet is marked unresolved. --all includes the data, var, and output nodes that the default view hides.

You can pretend the upstream results exist with a --facts file containing result blocks, and read the downstream nodes as vect would see them (Part 2 walks through this). Every node records result_sources, the facts its value came from, marked hypothetical, provided, or observed (COMP-FACT-2). With a workspace, vect inspect --workspace dev --observe stack.core.terraform.core reads that executor’s applied outputs from Inventory, so you see the real inputs downstream nodes would get. That needs something applied first, so in the fleet project we apply core alone:

vect apply --auto-approve --target stack.core.terraform.core

Then observe it, trimmed to one region’s app node:

node "stack.region[\"use1\"].terraform.app" {
  depends_on = ["stack.region[\"use1\"].var.network_id", "stack.region[\"use1\"].var.region"]
  result_sources = [{
    address    = "stack.core.terraform.core"
    provenance = "observed"
    version    = 1
  }]
  …
}

Without a workspace, a command makes no network calls: data sources that do IO, and vect.workspace, are typed unknowns. With --workspace, plan-time data blocks are read live for that workspace. A data "value" does no IO and is evaluated either way (COMP-MODE-1).

Determinism

The same configuration and facts always produce the same graph, node order, and diagnostics (COMP-PIPE-2). Many graphs have several valid orders; vect picks one by processing the nodes that are ready in a fixed order: stack path first, then node kind, then name, then instance key. Count indexes sort numerically ([2] before [10]) and for_each keys sort lexically. That’s why euw1 precedes use1 in the output above even though use1 was written first, and why the output of vect graph is something you can diff in a code review or in CI.

The order is a tie-breaker only. It says nothing about what must run in sequence: independent nodes, like the two regions, aren’t ordered by it at run time. Only edges are.

Addresses

Every node has a canonical address, used the same way in --target, fact files, moved and removed blocks, Inventory, locks, and diagnostics (LANG-ADDR-1 to LANG-ADDR-6). You’ve been reading them all along:

AddressNames
terraform.auditan executor at the root
stack.core.terraform.corean executor inside the core stack
stack.region["use1"].terraform.appan executor in one instance of a keyed stack
data.value.regionsa data block (prefix is data.)
stack.region["use1"].terraform.app::terraform_data.appa resource inside a Terraform root

The pattern is a chain of stack.<name>[key] steps, then <type>.<name>[key]. Executors have no executor. prefix, matching how you reference them.

The last row shows the :: separator. Everything before :: is a vect address. Everything after it is opaque to vect and means whatever the executor says it means; for terraform, it’s a Terraform resource address. vect uses it to narrow a run to part of a root:

Before targeting a resource, the project has to have been applied, because the plan compares against Inventory. Apply the whole fleet first (--auto-approve answers the prompts):

vect apply --auto-approve

Now target the resource (without the engine’s own lines):

vect plan --target 'stack.region["use1"].terraform.app::terraform_data.app'
stack.region["use1"].terraform.app: running
stack.region["use1"].terraform.app: planned no changes
plan of workspace "dev": succeeded (run 01a1e26b-19c1-7606-b3bb-cef4a57f7f09)
scope: --target stack.region["use1"].terraform.app::terraform_data.app (upstream: inventory)
  stack.region["use1"].terraform.app  no-op  no changes

The target put stack.region["use1"].terraform.app in scope and passed terraform_data.app to OpenTofu as -target. Leave off the key (stack.region.terraform.app) and it covers every instance; a bare stack (--target 'stack.region["use1"]') covers everything inside one instance. RUN-TARGET-1 through 8 define the details, including how upstream nodes outside the scope are read from Inventory.

Coming from Terraform: this is terraform -target=module.x.aws_thing.y, lifted to the project level. Because the address names a root and a place inside it, you can aim at one resource in one region without knowing which directory holds the root. Terraform warns that -target isn’t for routine use, and that warning applies here too; vect forwards it. Parsing then printing an address always returns the same string, so addresses copied from output are safe to paste into a command.

Per-block timeout

A node that does IO needs a deadline. timeout is a positive Go duration string ("10m", "90s") accepted on data, ephemeral, and executor blocks (LANG-META-6). It bounds a single call: the Plan, Apply, PlanDestroy, or Destroy of an executor, or one read of a data or ephemeral block. inspect shows it normalized:

node "terraform.migrate" {
  depends_on = ["terraform.db"]
  timeout    = "10m0s"
  …
}
A default you can swap: an executor call has 1h when timeout is unset, and a data or ephemeral read has 1m (EXEC-APPLY-5, COMP-MODE-7). Set timeout on a block to raise or lower either. A zero, negative, or unparseable value is a diagnostic. Like the other meta-arguments that shape a run, timeout can’t reference an executor’s output.

A read that exceeds its timeout fails that node and skips its dependents (EXEC-DATA-3). (Executors with a Waiter also take wait_timeout; that’s an executor topic.)

What you get

Putting it together, a few properties follow from “one graph, built from references”:

  • No glue. The order of ten roots across four stacks is whatever the references say. Nobody maintains a pipeline order or a remote_state data source.
  • Visible before it runs. graph and inspect work offline, so the order and the data flow can be reviewed in a pull request.
  • Cross-stack and cross-root edges are ordinary. A stack boundary changes what a block can see, not whether it can be ordered.
  • Fan-out is a graph transformation. for_each on a stack makes N copies of everything under it, addressable and individually targetable.
  • Mistakes are compile errors. Cycles, unknown references, and unknown values in places that need to be known are rejected before any executor is called.

Where to go next: how a stack scopes names and what flows across its boundary; how a project is bundled and composed from other projects; and how the graph executes: concurrency, memoization, and Temporal.