Gas City Formula Specification — v2 (formula_compiler 2.0)

​

0. Concept And Data Model

formula (TOML)
  → compiled recipe (flat, topologically ordered)
    → workflow root bead          (type "task", gc.kind = "workflow")
    + step beads                  (independently routable work, blocking deps only)
    + control beads               (controller-owned: check, retry, fanout,
                                   tally, drain, scope-check, workflow-finalize)

• The controller executes every control bead. The control dispatcher in internal/dispatch evaluates check and retry budgets, expands fan-outs, tallies votes, scatters drains, enforces scope failure policy, and finalizes the workflow. No agent participates in control execution.
• Agents execute only plain work beads. Step beads are independently Ready-visible and routable, so different steps of one workflow may be worked by different agents, pools, or providers.

formula = "pancakes"
description = "Make pancakes from scratch"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "dry"
title = "Mix dry ingredients"
description = "Combine flour, sugar, baking powder, salt in a large bowl."

[[steps]]
id = "wet"
title = "Mix wet ingredients"
description = "Whisk eggs, milk, and melted butter together."

[[steps]]
id = "combine"
title = "Combine wet and dry"
description = "Fold wet ingredients into dry. Do not overmix."
needs = ["dry", "wet"]

[[steps]]
id = "cook"
title = "Cook the pancakes"
description = "Heat griddle to 375F. Pour 1/4 cup batter per pancake."
needs = ["combine"]

[[steps]]
id = "serve"
title = "Serve"
description = "Stack pancakes on a plate with butter and syrup."
needs = ["cook"]

​

1. File Format

​

1.1. File Naming And Layers

[formulas].dir is no longer supported; use the well-known formulas/ directory

Compatibility: Builds predating the shared last-wins resolver (issue #2027, fixed by #2028) resolved gc formula show/cook/sling first-wins, letting imported pack formulas shadow same-name city overrides. If an override does not take effect, inspect gc formula show <name> against the layer you expect to win.

​

1.2. Top-Level Keys

​

1.3. Steps

​

1.4. Variables

formula = "deploy"
description = "Deploy {{env}} from {{branch}}"

[requires]
formula_compiler = ">=2.0.0"

[vars]
branch = "main"

[vars.env]
description = "Deployment environment"
required = true
enum = ["dev", "staging", "prod"]

[[steps]]
id = "deploy"
title = "Deploy {{env}}"

gc sling worker deploy --formula --var env=prod

• {{convoy_id}} — the input convoy of a targeted invocation. References must be spelled exactly {{convoy_id}} (any other spelling fails with convoy_id requires a targeted formulas v2 invocation), and any reference forces a targeted invocation (gc sling --on <formula> or gc formula cook --attach); an untargeted invocation fails with v2 formula "<name>" requires a target convoy. Enforcement happens at invocation time (section 3).
• {{bead_id}} — forbidden: bead_id is not available in v2 formulas; use convoy_id.
• {{issue}} — deprecated one-release compat alias resolving to the single tracked member of the input convoy; cook and sling print warnings: deprecated in formulas v2 and removed next release; migrate to the convoy_id work-bead derivation (gastownhall/gascity#2941).

​

1.5. Conditions

​

1.6. Loops

formula = "hanoi"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "moves"
title = "Tower moves"

[steps.loop]
range = "1..3"
var = "move_num"

[[steps.loop.body]]
id = "move"
title = "Move {move_num}"

Formula: hanoi

Steps (4):
  ├── hanoi.moves.iter1.move: Move 1
  ├── hanoi.moves.iter2.move: Move 2 [needs: hanoi.moves.iter1.move]
  ├── hanoi.moves.iter3.move: Move 3 [needs: hanoi.moves.iter2.move]
  └── hanoi.workflow-finalize: Finalize workflow [needs: hanoi.moves.iter3.move]

formula = "poll-until"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "poll"
title = "Poll for completion"

[steps.loop]
until = "probe.status == 'complete'"
max = 5

[[steps.loop.body]]
id = "probe"
title = "Probe the endpoint"

Formula: poll-until

Steps (2):
  ├── poll-until.poll.iter1.probe: Probe the endpoint
  └── poll-until.workflow-finalize: Finalize workflow [needs: poll-until.poll.iter1.probe]

​

1.7. Composition And Inheritance

• Child steps replace parent steps with the same ID whole-step (no field-level merge), preserving the parent’s position; new child steps append.
• Parent vars are inherited; child declarations override.
• phase is taken from the child, else the first parent that declares one.
• pour is monotonic: any ancestor’s pour = true sticks; a child cannot opt out.
• contract and requires come from the child, else the first parent — and requirement constraints from every parent are still collected and validated as a set (section 5).
• Circular extends chains must fail (circular extends detected: a -> b -> a).

​

1.8. Description Files

description_file = "../assets/workflows/review/local-review.md"

• Files larger than 4096 bytes are not inlined. The step’s description is replaced by a generated pointer that directs the agent to read the file at its resolved path.
• A v2 formula must fail fast on an unresolvable description_file. (v1 formulas skip it best-effort and keep any inline description.)

​

1.9. Validation

• formula name is required.
• contract, if set, must be "graph.v2" (contract: invalid value "<value>" (must be graph.v2)).
• type must be workflow, expansion, or aspect.
• A var must not combine required = true with a default.
• Step id is required and globally unique, including children.
• Step title is required unless expand is set.
• priority must be 0–4.
• depends_on / needs entries must reference known step IDs (including children).
• waits_for must match all-children, any-children, or children-of(step-id) with the referenced step present (waits_for has invalid value "<value>" (must be all-children, any-children, or children-of(step-id))).
• on_complete: for_each and bond must be set together; for_each must start with output.; parallel and sequential are mutually exclusive.
• tally requires on_complete; mode must be majority, unanimous, or any-pass.
• check: max_attempts ≥ 1; the inner check table is required with mode = "exec" (the only supported checker) and a non-empty path. Unexpected keys fail: step.check: unsupported key "<key>" (expected max_attempts or check) / step.check.check: unsupported key "<key>" (expected mode, path, or timeout).
• retry: max_attempts ≥ 1; on_exhausted must be hard_fail or soft_fail.
• drain: see section 3.3 for field constraints and incompatibilities.
• timeout must be a positive Go duration and requires check.
• Loops (validated during control-flow expansion): body non-empty; exactly one of count / until / range; max required with until.

​

2. Compilation

• Blocking dependency edges only. Step beads carry blocks edges from needs / depends_on (and readiness-blocking waits-for edges from waits_for). The compiler creates no parent-child edges between graph steps; nesting in children affects ID namespacing and validation, not runtime hierarchy.
• workflow-finalize is appended. A control step with ID workflow-finalize (kind workflow-finalize) is added depending on every sink step, so it becomes Ready exactly when all other work is terminal.
• The root blocks on the finalize step. The workflow root bead is made to depend on workflow-finalize (or, when a recipe has no finalize step, on every step whose gc.kind is not one of the generated run, check, retry-run, retry-eval, or spec kinds). Consequence: the root is never Ready-visible while the workflow runs and only surfaces when the workflow completes. Step beads — not the root — are the Ready-visible work that wakes agents and pools.
• Non-blocking tracks edges to the root. Batch instantiation connects every non-root node to the root with a tracks edge so cascade deletion from the root discovers all workflow beads without making the root a readiness blocker.
• Step beads keep routable types. Non-root graph step beads are not coerced to scaffolding types, so Ready() surfaces them for worker claim and each step is independently routable.
• Cycles are rejected: v2 formula "<name>" contains a dependency cycle.

Formula: pancakes
Description: Make pancakes from scratch

Steps (6):
  ├── pancakes.dry: Mix dry ingredients
  ├── pancakes.wet: Mix wet ingredients
  ├── pancakes.combine: Combine wet and dry [needs: pancakes.dry, pancakes.wet]
  ├── pancakes.cook: Cook the pancakes [needs: pancakes.combine]
  ├── pancakes.serve: Serve [needs: pancakes.cook]
  └── pancakes.workflow-finalize: Finalize workflow [needs: pancakes.serve]

Root: mc-79s
Created: 7
pancakes -> mc-79s
pancakes.combine -> mc-265
pancakes.cook -> mc-nia
pancakes.dry -> mc-b8g
pancakes.serve -> mc-k3q
pancakes.wet -> mc-0ez
pancakes.workflow-finalize -> mc-9vb

Started workflow mc-btj (formula "pancakes") → mayor

​

3. Runtime

​

3.1. Check

formula = "checked"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "implement"
title = "Implement the feature"

[steps.check]
max_attempts = 3

[steps.check.check]
mode = "exec"
path = "scripts/verify.sh"
timeout = "2m"

Formula: checked

Steps (4):
  ├── checked.implement.spec: Step spec for Implement the feature (spec)
  ├── checked.implement.iteration.1: Implement the feature
  ├── checked.implement: Implement the feature [needs: checked.implement.iteration.1]
  └── checked.workflow-finalize: Finalize workflow [needs: checked.implement]

​

3.2. Retry

formula = "retry-fetch"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "fetch"
title = "Fetch the dataset"

[steps.retry]
max_attempts = 3
on_exhausted = "soft_fail"

Formula: retry-fetch

Steps (4):
  ├── retry-fetch.fetch.spec: Step spec for Fetch the dataset (spec)
  ├── retry-fetch.fetch.attempt.1: Fetch the dataset
  ├── retry-fetch.fetch: Fetch the dataset [needs: retry-fetch.fetch.attempt.1]
  └── retry-fetch.workflow-finalize: Finalize workflow [needs: retry-fetch.fetch]

• pass — the control closes gc.outcome = pass, copying the attempt’s gc.output_json and non-gc.* metadata upward.
• hard — the control closes gc.outcome = fail with gc.final_disposition = hard_fail; no further attempts.
• transient — with budget left, the controller spawns the next attempt; at max_attempts, exhaustion applies on_exhausted: hard_fail closes the control gc.outcome = fail and gc.final_disposition = hard_fail; soft_fail closes it gc.outcome = pass with gc.final_disposition = soft_fail so downstream work continues with degraded coverage.

​

3.3. Drain

formula = "review-batch"
description = "Run a work formula for each convoy member"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "scatter"
title = "Process every member"

[steps.drain]
formula = "mol-do-work"
context = "separate"
max_units = 20

​

3.4. On-Complete And Tally

formula = "vote"
description = "Fan out voters and tally their verdicts"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "survey"
title = "Survey reviewers"

[steps.on_complete]
for_each = "output.reviewers"
bond = "mol-do-work"
parallel = true

[steps.on_complete.vars]
reviewer = "{item.name}"

[steps.tally]
vote_field = "verdict"
mode = "majority"

​

3.5. Scopes And Failure Policy

formula = "scoped"

[requires]
formula_compiler = ">=2.0.0"

[[steps]]
id = "body"
title = "Worktree scope"
needs = ["implement"]
metadata = { "gc.kind" = "scope", "gc.scope_name" = "worktree", "gc.scope_role" = "body" }

[[steps]]
id = "implement"
title = "Implement the change"
metadata = { "gc.scope_ref" = "body", "gc.scope_role" = "member", "gc.on_fail" = "abort_scope" }

[[steps]]
id = "cleanup"
title = "Tear down the worktree"
needs = ["body"]
metadata = { "gc.kind" = "cleanup", "gc.scope_ref" = "body", "gc.scope_role" = "teardown" }

​

4. Accepted But Inert

• Until-loop re-execution. Compiling an until loop validates the condition and writes a loop:{"until":...,"max":...} label on the first body step (the loop expander in internal/formula/controlflow.go), but no component — neither the v1 cook path nor the v2 control dispatcher — reads that label. An until loop therefore runs exactly one iteration. Use check (section 3.1) for controller-driven re-execution.
• Gate type vocabulary. [steps.gate] synthesizes a real gate bead that blocks its step until the gate bead is closed (manually or by an external watcher), but the type values gh:run, gh:pr, timer, human, and mail are doc-comment vocabulary in internal/formula/types.go — the parser never validates them and no bundled watcher acts on them. Zero bundled formulas use gate.
• waits_for gate modes. waits_for compiles to a readiness-blocking waits-for dependency edge plus a recorded gate mode, but no current dispatcher logic interprets the all-children / any-children distinction. Zero bundled formulas use waits_for.
• vars.<name>.type. The variable type field (string, int, bool) is parsed into the variable definition (internal/formula/types.go) but never enforced; only required, enum, and pattern are validated at instantiation.

​

5. Conformance And Compatibility

​

Opt-in surface

[requires]
formula_compiler = ">=2.0.0"

​

Explicit declaration rule

requires: formulas that use graph-only constructs must declare [requires] formula_compiler = ">=2.0.0" or the deprecated contract = "graph.v2" explicitly

​

Requirement composition

formula.compiler_requirement_conflict: formula "<name>" has non-overlapping formula_compiler requirements: <constraint> from <source>; ...

formula.compiler_requirement_unsatisfied: formula requires formula_compiler <constraint> from <source>, but this city has formula compiler capability 1.0.0 because [daemon] formula_v2 is disabled

formula "<name>" requires formula compiler v2 but formula_v2 is disabled; enable [daemon] formula_v2 or lower the formula requirements

​

Doctor and lint

replace deprecated contract = "graph.v2" with [requires] formula_compiler = ">=2.0.0"; enable [daemon] formula_v2 or lower requirements; fix invalid requirements and parent/child conflicts

​

Differences from v1

• gc converge accepts only v1 formulas and rejects v2:
  convergence wisps do not support v2 formula "<name>"; use a v1 formula until convergence has an explicit input convoy target
  
  The v2 construct for iterate-until-verified semantics is the check loop (section 3.1); gc converge is the pre-v2 command for this pattern.
• Container dependencies do not gate on children. Under v1, a step that needs a parent waits for all of that parent’s children; the v2 compiler creates no parent-child edges, so the same dependency gates only on the parent step itself. This is a tracked gap (#3451), not a contract guarantee — until it lands, enumerate the children explicitly in needs.

formula "<name>" root is a molecule container, not Ready-visible work; scale-from-zero pools will not wake for this wisp. Convert the formula to phase="vapor"/root-only or formulas v2 before routing it to a pool

​

Deprecated surfaces