​

Formulas & Molecules

Last verified against code: 2026-03-17

​

Summary

• Gas City owns formula discovery and layer resolution.
• The beads backend owns formula materialization.
• bd is the full-featured backend for real formula execution today.

​

Key Concepts

• Formula file: A *.formula.toml file selected through formula layers.
• Formula layers: Ordered directories computed from packs, city config, and rig config. Higher-priority layers shadow lower-priority files by name.
• Molecule: A runtime instance created from a formula.
• Wisp: An ephemeral molecule created for dispatch or order execution.
• Attached molecule: A formula instantiated onto an existing bead via Store.MolCookOn.
• Convergence formula subset: The subset of formula metadata used by the convergence subsystem, validated in internal/convergence/formula.go.

​

Architecture

formula layers
  from config + packs
        |
        v
ResolveFormulas()
cmd/gc/formula_resolve.go
        |
        v
.beads/formulas/*.formula.toml
        |
        v
Store.MolCook / Store.MolCookOn
        |
        +--> BdStore     -> bd mol wisp / bd mol bond
        +--> exec.Store  -> script mol-cook / mol-cook-on
        \--> Mem/File    -> simplified molecule root for tests/tutorials

​

Resolution

1. Scans each layer for *.formula.toml
2. Keeps the highest-priority winner for each filename
3. Symlinks winners into <target>/.beads/formulas/
4. Removes stale formula symlinks without touching real files

​

Instantiation

• Store.MolCook(formula, title, vars) creates a new molecule or wisp
• Store.MolCookOn(formula, beadID, title, vars) attaches a molecule to an existing bead

• BdStore in internal/beads/bdstore.go delegates to bd mol wisp and bd mol bond, then parses the returned root bead ID.
• exec.Store in internal/beads/exec/exec.go forwards mol-cook and mol-cook-on to a user script.
• MemStore and FileStore create a simplified molecule root bead. They are suitable for tests and tutorials, not full formula execution.

​

Dispatch and Orders

• cmd/gc/cmd_sling.go creates wisps during gc sling --formula and attached molecules via --on.
• cmd/gc/order_dispatch.go creates wisps when formula-backed orders fire.

​

Garbage Collection

​

Invariants

• Formula resolution is last-wins by filename across ordered layers.
• ResolveFormulas() only mutates symlinks under .beads/formulas/; it never overwrites real files.
• Molecule creation always goes through the configured beads.Store.
• Full multi-step formula execution is backend-dependent today; BdStore is the production path.
• Wisp garbage collection only targets closed molecules past the configured TTL.

​

Interactions

​

Code Map

​

Configuration

• city packs
• [formulas].dir in city.toml
• rig packs
• [[rigs]].formulas_dir

[daemon]
wisp_gc_interval = "5m"
wisp_ttl = "24h"

​

Testing

• cmd/gc/formula_resolve_test.go verifies winner selection, stale cleanup, and real-file preservation
• internal/beads/bdstore_test.go verifies bd mol wisp / bd mol bond wiring and root ID parsing
• internal/beads/memstore_test.go and internal/beads/filestore_test.go verify simplified molecule creation for test-oriented stores
• cmd/gc/order_dispatch_test.go and cmd/gc/cmd_sling_test.go cover the higher-level formula dispatch paths

​

Known Limitations

• Gas City does not currently own a general in-process formula parser for the main runtime path.
• Step-bead materialization is backend-dependent; production behavior comes from bd.
• Tutorial and in-memory stores intentionally implement a smaller molecule model than the production backend.

​

See Also

• Formula Files for the file layout
• Dispatch for sling-based formula routing
• Orders for formula-backed scheduled work
• Bead Store for the MolCook interface boundary