​

Formula Infrastructure Migration: Beads to Gas City

​

Context

​

Current flow (bd shell-out)

gc sling --formula mol-X
  -> BdStore.MolCook("mol-X", ...)
    -> exec: bd mol wisp mol-X --json
      -> formula.Parse + Resolve + ApplyControlFlow + ...
      -> cookFormulaToSubgraph (steps -> issues)
      -> spawnMoleculeWithOptions (issues -> dolt store)
    <- JSON: {new_epic_id: "..."}
  <- root bead ID

​

Target flow (native)

gc sling --formula mol-X
  -> formula.Compile(ctx, "mol-X", searchPaths, vars)
    -> Parse + Resolve + ApplyControlFlow + ApplyAdvice + ...
  <- *formula.Recipe (compiled steps with {{vars}} intact)
  -> molecule.Cook(ctx, store, recipe, opts)
    -> Substitute(vars) in titles/descriptions
    -> store.Create(root bead)
    -> for each step: store.Create(step bead) + store.DepAdd(...)
  <- molecule.Result{RootID, IDMapping}

​

Goals

1. Gas City can compile formulas and instantiate molecules without bd.
2. Correct architectural layering: formula compilation (Layer 2-4) depends on Store (Layer 0-1), not the other way around.
3. MolCook/MolCookOn removed from the beads.Store interface — Store is CRUD, not compilation.
4. All existing callers (sling, orders, convergence, API) use the native path.
5. All formula tests from beads pass in Gas City.
6. No behavioral changes from the user’s perspective — gc sling --formula works identically.

​

Non-Goals

• Porting bd cook --persist (database-backed proto beads). Gas City uses ephemeral in-memory compilation exclusively.
• Porting bd mol pour as a standalone CLI command. Instantiation happens via gc sling, not a separate command.
• Porting bd mol bond as a standalone CLI command. Bonding is handled via gc sling --on.
• Changing the .formula.toml file format. Full backward compatibility.
• Porting bd mol squash, bd mol burn, bd mol distill, or other molecule lifecycle commands. Those are beads-specific.

​

Ownership

• Gas City owns: internal/formula/ (compilation) + internal/molecule/ (instantiation). All future formula features land here first.
• Beads retains: internal/formula/ as a frozen copy for backward compatibility with bd cook/bd mol wisp. No new features.
• Sync strategy: None. This is a deliberate fork, not a shared module. Beads’ formula package served its purpose as a prototype. Gas City’s copy is the production implementation. Beads can deprecate its copy at its own pace.
• Why not a shared Go module: The formula package will diverge as Gas City adds Recipe types, context.Context support, and Gas City-specific compilation stages. A shared module would couple two projects with different release cadences for no benefit — the package is small enough that independent ownership is simpler than coordinated releases.

​

Architecture

​

New packages

internal/
  formula/           # NEW -- ported from beads/internal/formula/
    types.go         # Formula, Step, ComposeRules, VarDef, Gate, ...
    parser.go        # Parser: TOML/JSON loading, inheritance, caching
    condition.go     # Runtime condition evaluation (gates)
    stepcondition.go # Compile-time step filtering
    controlflow.go   # Loop expansion, branch wiring, gate application
    expand.go        # Expansion template application
    range.go         # Range expression parsing
    advice.go        # Aspect advice operators
    compile.go       # NEW -- top-level Compile() entry point
    recipe.go        # NEW -- Recipe type (compiled output)

  molecule/          # NEW -- instantiation layer
    molecule.go      # Cook/CookOn convenience API + Result type
    instantiate.go   # core instantiation logic

​

Package layering and import constraints

Layer 4  cmd/gc/         imports: formula, molecule, beads, config
Layer 3  molecule/       imports: formula, beads
Layer 2  formula/        imports: (stdlib + BurntSushi/toml only)
Layer 1  beads/          imports: (stdlib only)
Layer 0  config/         imports: (stdlib + BurntSushi/toml only)

• formula/ NEVER imports molecule/, beads/, or config/
• molecule/ NEVER imports cmd/gc/ or config/
• beads/ NEVER imports formula/ or molecule/

​

Key types

// formula/recipe.go -- output of compilation
type Recipe struct {
    Name        string
    Description string
    Steps       []RecipeStep            // flattened, ordered (root is Steps[0])
    Deps        []RecipeDep             // all dependency edges
    Vars        map[string]*VarDef      // variable definitions (for default handling)
    Phase       string                  // "vapor" or "liquid"
    Pour        bool                    // formula recommends full materialization
    RootOnly    bool                    // true for patrol wisps (root only, no children)
}

type RecipeStep struct {
    ID          string                  // namespaced: "formula-name.step-id"
    Title       string                  // may contain {{variables}}
    Description string
    Notes       string
    Type        string                  // "task", "bug", "epic", "gate", etc.
    Priority    *int
    Labels      []string
    Assignee    string
    IsRoot      bool                    // true for the root epic
    Gate        *RecipeGate             // async gate spec (if step has a gate)
}

type RecipeGate struct {
    Type    string                      // "all-children", "any-children", etc.
    ID      string
    Timeout string
}

type RecipeDep struct {
    StepID      string
    DependsOnID string
    Type        string                  // "blocks", "parent-child", "waits-for"
    Metadata    string                  // JSON for waits-for gate metadata
}

// formula/compile.go -- top-level entry point
// Compile loads a formula by name and runs the full compilation pipeline.
// The returned Recipe contains {{variable}} placeholders -- substitution
// happens at instantiation time, not compilation time.
// vars is used only for compile-time step condition filtering (steps with
// conditions that evaluate to false are excluded).
func Compile(ctx context.Context, name string, searchPaths []string, vars map[string]string) (*Recipe, error)

1. parser.LoadByName(name) — load formula TOML from search paths
2. parser.Resolve(f) — resolve inheritance (extends chains)
3. ApplyControlFlow(steps, compose) — loops, branches, gates
4. ApplyAdvice(steps, advice) — inline advice rules
5. ApplyInlineExpansions(steps, parser) — step-level expand field
6. ApplyExpansions(steps, compose, parser) — compose.expand/map operators
7. Aspect loading + ApplyAdvice for each compose.aspects entry
8. FilterStepsByCondition(steps, vars) — compile-time step filtering
9. MaterializeExpansion — standalone expansion formula handling
10. toRecipe(resolved) — flatten step tree to Recipe with namespaced IDs, gate siblings, and type promotions (epic for steps with children)

// molecule/molecule.go -- convenience API
type Options struct {
    Title          string              // override root bead title (optional)
    Vars           map[string]string   // variable substitution values
    ParentID       string              // attach to existing bead (for CookOn)
    IdempotencyKey string              // set on root bead metadata (for convergence)
}

type Result struct {
    RootID    string
    IDMapping map[string]string        // recipe step ID -> bead ID
    Created   int
}

// Cook compiles a formula and instantiates it as a molecule in one step.
// This is the convenience wrapper that most callers should use.
func Cook(ctx context.Context, store beads.Store, formulaName string, searchPaths []string, opts Options) (*Result, error)

// CookOn compiles a formula and attaches it to an existing bead.
func CookOn(ctx context.Context, store beads.Store, formulaName string, searchPaths []string, opts Options) (*Result, error)

// Instantiate creates beads from a pre-compiled Recipe.
// Use this when you need to inspect/modify the Recipe before instantiation.
func Instantiate(ctx context.Context, store beads.Store, recipe *formula.Recipe, opts Options) (*Result, error)

​

Store interface changes

// REMOVED
MolCook(formula, title string, vars []string) (string, error)
MolCookOn(formula, beadID, title string, vars []string) (string, error)

​

Partial failure semantics

• Best-effort cleanup on failure. If Create fails on step K, close beads 0..K-1 with a molecule_failed metadata flag. Callers can detect and clean up orphans.
• Idempotency key set atomically with root creation. For convergence, Options.IdempotencyKey is set as metadata on the root bead during Store.Create (via Bead.Metadata), not as a separate SetMetadata call. This narrows the crash window to zero for the idempotency check.
• Fault-injection tests required. Test Create-fails-on-Nth-step, DepAdd-fails-after-creates, and metadata-set-failure scenarios.

​

Complete caller inventory

​

Per-caller migration pattern

​

Search path helper

// SearchPaths returns the ordered formula search directories for a rig.
// Falls back to city-level layers if no rig-specific layers exist.
func (fl *FormulaLayers) SearchPaths(rigName string) []string

​

Variable handling

• Compile time: vars are used only for FilterStepsByCondition (step condition field evaluation). The Recipe preserves {{placeholders}}.
• Instantiate time: Options.Vars are substituted into titles, descriptions, and notes. Defaults from Recipe.Vars are applied first.

​

Migration phases

​

Phase 1: Port formula package (PR 1)

• Package import paths (no external changes needed — zero beads deps)
• github.com/BurntSushi/toml is already in Gas City’s go.mod
• Verify all tests pass with go test ./internal/formula/...

​

Phase 2: Create molecule package (PR 2, additive)

• Happy path: compile + instantiate simple formula
• Variable substitution in titles/descriptions
• Dependency wiring (needs, depends_on, parent-child)
• Nested children (epic with sub-steps)
• Gate step synthesis
• RootOnly mode (patrol wisps)
• Fault injection: Create-fails-on-Nth-step, DepAdd-fails-after-creates
• IdempotencyKey set atomically with root

​

Phase 3: Switch callers with rollback toggle (PR 3)

• GC_NATIVE_FORMULA=true (default): use native compilation
• GC_NATIVE_FORMULA=false: fall back to Store.MolCook (bd shell-out)

​

Phase 4: Remove MolCook from Store interface (PR 4, after bake period)

• Remove MolCook and MolCookOn from beads.Store interface
• Remove implementations from BdStore, MemStore, FileStore, exec.Store
• Remove GC_NATIVE_FORMULA toggle
• Remove mol-cook/mol-cook-on from exec.Store script operations
• Update exec-beads-provider.md to remove mol-cook from the wire protocol

​

Phase 5: CLI commands (optional, low priority)

gc formula list                    # list available formulas
gc formula show <name>             # preview compiled recipe
gc formula show <name> --var k=v   # preview with variable substitution

​

Testing strategy

​

Golden fixture tests (mandatory, CI gate)

1. Simple (2 steps, no deps)
2. Variables (required + defaults)
3. Dependencies (needs, depends_on)
4. Nested children (3 levels)
5. Loops (fixed count)
6. Conditions (step filtering)
7. Gates (async coordination)
8. Advice/aspects (before/after)
9. Expansions (inline + compose)
10. Inheritance (extends chain)

​

Unit tests (ported)

​

Unit tests (new)

• internal/molecule/instantiate_test.go with MemStore
• internal/formula/compile_test.go for the Compile entry point
• Fault injection tests for partial failure scenarios

​

Integration tests

• Sling with --formula flag using MemStore
• Order dispatch with formula-based orders
• Convergence loop iteration with native CookOn
• exec.Store with CRUD-only script (no mol-cook)

​

Test double migration

• errStore, selectiveErrStore, recordingStore in cmd_sling_test.go
• These are updated to compose molecule.Instantiate over their base Store, or to inject pre-compiled Recipes via a test helper.

​

Risks and mitigations

​

Migration order and dependencies

Phase 1 (formula port + compile) --- no deps, start immediately
     |
Phase 2 (molecule package) --- depends on Phase 1, additive
     |
Phase 3 (switch callers + toggle) --- depends on Phase 2
     |                                 minimum bake period before Phase 4
Phase 4 (remove MolCook) --- depends on Phase 3 bake
     |
Phase 5 (CLI commands) --- depends on Phase 1, independent of 2-4