Gas City Formula Specification — v1 (formula_compiler 1.0)

​

0. Concept And Data Model

formula (TOML)
  → compiled recipe (flat list + dependency edges)
    → molecule container root      (type "molecule")
    + child step beads             (parent-child edges to their container;
                                    blocking edges from needs/depends_on)

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

[[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

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

​

1.4. Variables

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

[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

​

1.5. Conditions

​

1.6. Loops

formula = "hanoi"

[[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 (3):
  ├── 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]

formula = "poll-until"

[[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 (1):
  └── poll-until.poll.iter1.probe: Probe the endpoint

​

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). A v1 child extending a v2 parent inherits the v2 requirement and stops being a v1 formula.
• 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 v1 formula skips an unresolvable description_file best-effort: the reference is left unconsumed and any inline description is kept, with no diagnostic. (v2 formulas fail fast instead.)

​

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))).
• timeout must be a positive Go duration and requires check — both v2-only; a bare timeout in a v1 formula fails with a message routing convergence gate scripts to convergence.gate_timeout / --gate-timeout.
• Loops (validated during control-flow expansion): body non-empty; exactly one of count / until / range; max required with until.

​

2. Compilation

• Namespaced step IDs. Every step gets the recipe ID <formula>.<step>; nested children extend the path (<formula>.<parent>.<child>). The namespaced ID is stamped on each cooked step bead as gc.step_ref metadata.
• Parent-child containment. Every step carries a parent-child edge to its container — the molecule root for top-level steps, the enclosing step for children. A step with children is promoted to issue type epic.
• Blocking edges. needs / depends_on compile to blocks edges; waits_for compiles to a readiness-blocking waits-for edge plus a gate:<value> label on the cooked step (section 4).
• Gate synthesis. A [steps.gate] table synthesizes a gate bead (recipe ID <formula>.gate-<step>, type gate, title Gate: <type> <id>) that is a child of the step’s container, plus a blocks edge from the gated step to it: the step stays blocked until the gate bead is closed.
• Root. The recipe root is type molecule, priority 2. Its title is the formula name, or the {{title}} placeholder when a title var is declared; its description is the formula description, or {{desc}} when a desc var is declared.
• Root-only wisps. When the formula sets phase = "vapor" without pour, or has no steps, the recipe is root-only: the root is type task stamped gc.kind = "wisp", and steps are not materialized as beads — the root bead itself is the work, carrying only the formula’s title and description. Authors of root-only formulas should put the work instructions in the formula description. Setting pour = true forces full materialization (checkpoint recovery) regardless of phase.
• Step-type coercion at instantiation. Non-root step beads typed task (the default) are stamped type step so Ready() and bd ready skip formula scaffolding — the molecule root is the actionable unit. Other explicit types (bug, epic, …) are preserved.
• Root stamping. Non-batch instantiation stamps gc.formula_hash (SHA-256 of the raw formula file bytes) and gc.formula_source on the root; gc formula version-check <bead-id> compares the stored hash against the on-disk recipe to detect formula drift since spawn.

Formula: pancakes
Description: Make pancakes from scratch

Steps (5):
  ├── 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]

  ├── feature.build: Build the feature (epic)
  ├── feature.build.api: Implement the API

Root: mc-8qi
Created: 6
pancakes -> mc-8qi
pancakes.combine -> mc-2x7
pancakes.cook -> mc-mjm
pancakes.dry -> mc-pzz
pancakes.serve -> mc-gzg
pancakes.wet -> mc-k1b

Slung formula "pancakes" (wisp root mc-98o) → worker

Formula: patrol
Description: Patrol loop worked from the root bead
Phase: vapor
Root only: true

Steps (1):
  └── patrol.scan: Scan for stale work

Root: mc-lbd
Created: 1
patrol -> mc-lbd

​

3. Runtime

• Agents advance work. The molecule is worked by the agent it is slung or hooked to; the bead store’s blocking edges sequence the steps. Neither the molecule container root nor its default-typed step beads surface through Ready() (section 2) — the molecule routes as a unit by being assigned to an agent directly, which is also why scale-from-zero pools cannot wake for stepped molecules (section 5).
• Targeted invocations. gc sling <target> <bead-id> --on <formula> injects the issue variable and routing variables specified in section 1.4. Formula slings do not create an auto-convoy; convoys, where they exist, track members through non-blocking tracks edges that never gate readiness.
• Completion. The molecule root is auto-closed by the bd close hook when every transitive descendant is terminal (close reason molecule autoclose: all step children closed). Container dependents unblock at that point (section 1.3).
• Garbage collection. The core pack’s reaper exec order (cooldown trigger, 30m interval) closes stale wisps whose parents or roots are closed, purges old closed molecule data, and closes TTL-expired beads.

​

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.
• 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 component 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

​

Contract selection

​

v2-only constructs are rejected

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

​

Convergence currently requires v1

convergence wisps do not support v2 formula "<name>"; use a v1 formula until convergence has an explicit input convoy target

​

Ready-visibility and pools

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

warning: pool order "<order>" uses formula "<name>" whose 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