Skip to content

Gas City Formulas Catalog

Purpose: Define when Bluefly uses Gas City formulas, authoring rules, and where definitions live.

Upstream: Understanding formulas, Formula spec v2, Command execution trust boundaries — formula vars are explicitly untrusted data; do not interpolate them into shell.

Definitions live in: pack formulas/ directories — not this catalog.

A Formula is a reusable multi-step workflow DAG. Cooking or slinging materializes Beads. This catalog states admission rules and authoring standards, not a hand-maintained formula inventory.

Materialization (Gas City 1.4.x & Beads 1.2.2): A Formula compiles into an addressable graph-workflow execution — materialized as a root bead plus child step beads with projected dependencies. Ephemeral execution state resides in high-churn SQLite (<city>/.gc/store/), while durable work tickets and receipts persist in Dolt and survive orchestrator/session restarts.

When to use a formula

Use a formula when work needs:

  • multi-step agent judgment
  • durable beads / receipts
  • routing across agents or pools
  • fan-in / fan-out dependency between steps
  • a reusable method shared by packs or cities

When not to use a formula

Keep with the native owner instead:

Work Owner
Deterministic CI gate GitLab CI / gitlab_components
Host install / Dolt server process IaC
One-shot deploy projection existing gc-site-bind
Trivial shell glue Prefer exec order or delete — almost never a formula

Relationship to Orders & Events

The native Gas City dispatch loop coordinates execution: 

EVENT / TRIGGER -> ORDER -> FORMULA (DAG) -> gc sling <agent> <bead> -> AGENT EXECUTION -> BEAD RECEIPT
- Formula owns how (workflow logic, step graph, variables, drains, checks). - Order owns when/where/against which pool/scope the formula fires (gc-orders.md).

Worked examples (Mountain-layer usage)

  • AMCS: Convoy "AMCS Composer convergence" runs Formula=drupal-change via Order=amcs-release-validation-manual (confirmed in gc-orders.md) against the amcs Rig.
  • DevOps: Convoy "Shared CI Estate Convergence" would run a Formula such as shared-ci-migration against the iac / gitlab_components Rigs — illustrative; confirm it exists as a pack-defined formula before treating it as deployed.

These show how a Convoy (Bluefly portfolio taxonomy — see gc-catalog.md) composes with Formula/Order/Rig. They are not a formula inventory.

Schema version

Always use [requires] formula_compiler = ">=2.0.0" (schema v2) for new formulas.

Version Produces Step routing
v1 (legacy) single container bead orchestrator routes once
v2 (required) independent step beads each step routes and executes independently

Step graph, fan-in, and drains

Steps may declare needs = [...] to express dependencies. Steps without needs are roots and run immediately. Multiple needs entries express fan-in (parallel convergence).

[[steps]]
id = "dry"
title = "Mix dry ingredients"

[[steps]]
id = "wet"
title = "Mix wet ingredients"

[[steps]]
id = "combine"
title = "Combine wet and dry"
needs = ["dry", "wet"]   # waits for both — fan-in

Variables

Declare variables under [vars.*]:

[vars.title]
description = "Feature description"
required = true

[vars.branch]
default = "main"

[vars.priority]
default = "normal"
enum = ["low", "normal", "high", "critical"]

Pass at cook/sling time: gc formula cook feature-work --var title="Auth overhaul"

Control flow

Construct Resolves at Effect
condition compile time Omit a step when a variable condition is false
loop compile time Expand copies of a body by count or range
check runtime Re-dispatch step until a validation script exits 0
retry runtime Re-dispatch on transient failure
drain runtime Fan out a sub-formula over a collection (max_units, member_access) — v2-only, hard-fails v1
on_complete runtime Bond to a downstream formula over for_each = "output.*" results — v2-only, hard-fails v1

Check (runtime feedback loop)

[steps.check]
max_attempts = 2

[steps.check.check]
mode = "exec"
path = "scripts/verify.sh"
timeout = "30s"

Retry (transient failure)

[steps.retry]
max_attempts = 3
on_exhausted = "soft_fail"   # or "hard_fail" (default)

Key commands

gc formula list                                       # list all formulas in active packs
gc formula show <name>                                # compiled DAG with control step
gc formula show <name> --var key=value                # preview with variable binding
gc formula cook <name>                                # materialize beads WITHOUT routing
gc sling <agent> <root-bead> --formula                # compile + materialize + route
gc order run <order-name>                             # fire an order (which runs a formula)

Rules

  • Always use schema = 2 ([requires] formula_compiler = ">=2.0.0").
  • Prefer pack-owned formulas over city-local copies.
  • Do not paste full workflow implementations into Engineering-Standard; link pack sources.
  • Do not promote incident runbooks into formulas without a reusable, reviewed method.
  • Do not invent formulas for deterministic shell work — use an exec order.
  • Formula variables must not carry secrets; pass secrets through provider/env injection.
  • Prefer upstream formula semantics; Bluefly docs explain constraints and ownership only.
  • No personal home paths or workstation absolute paths in this catalog (use $WORKSPACE_ROOT).