gastown/docs/molecular-chemistry.md

Molecular Chemistry: Work Composition in Gas Town

"Work is fractal. Money is crystallized labor. Blockchain was the mechanism searching for its purpose."

Gas Town is a work composition and execution engine. This document describes the chemistry-inspired system for expressing, instantiating, and executing work at any scale - from single tasks to massive polymers that can grind through weekends of autonomous operation.

The Steam Engine Metaphor

Gas Town is an engine. Engines do work and generate steam.

Claude = Fire (the energy source)
Claude Code = Steam Engine (harnesses the fire)
Gas Town = Steam Train (coordinates engines on tracks)
Beads = Railroad Tracks (the persistent ledger of work)

In our chemistry:

• Proto molecules are the fuel (templates that define workflows)
• Mols are liquid work (flowing, dynamic, adapting as steps complete)
• Wisps are the steam (transient execution traces that rise and dissipate)
• Digests are the distillate (condensed permanent records of completed work)

The Three Phases of Matter

Work in Gas Town exists in three phases, following the states of matter:

Phase	Name	State	Storage	Behavior
Solid	Proto	Frozen template	.beads/ (template label)	Crystallized, immutable, reusable
Liquid	Mol	Flowing instance	.beads/	Dynamic, adapting, persistent
Vapor	Wisp	Ephemeral trace	.beads-wisp/	Transient, dissipates, operational

Proto (Solid Phase)

Protos or protomolecules are frozen workflow patterns - crystallized templates that encode reusable work structures. They're the "molds" from which instances are cast.

## Molecule: engineer-in-box
Full workflow from design to merge.

## Step: design
Think carefully about architecture.
Needs: (none)

## Step: implement
Write the code.
Needs: design

## Step: review
Perform initial code review.
Needs: implement

## Step: test
Write and run tests.
Needs: review

## Step: submit
Submit for merge.
Needs: test

Properties:

• Considered immutable once defined (frozen), though editable
• Named (e.g., mol-engineer-in-box, wisp-deacon-patrol)
  • Can have any name, but convention says how they will materialize.
• Stored in permanent beads with template label
• Can be composed into larger protos (compounds, polymers)

Mol (Liquid Phase)

Mols are flowing work instances - live executions that adapt as steps complete, status changes, and work evolves.

Properties:

• Identified by head bead ID (e.g., bd-abc123)
• Dynamic - steps transition through states
• Persistent - survives sessions, crashes, context compaction
• Auditable - full history in beads

Wisp (Vapor Phase)

Wisps are ephemeral execution traces - the steam that rises during work and dissipates when done.

Properties:

• Stored in .beads-wisp/ (gitignored, never synced)
• Single-cycle lifetime
• Either evaporates (burn) or condenses to digest (squash)
• Used for patrol cycles, operational loops, routine work

Phase Transition Operators

Work transitions between phases through specific operators:

                    ┌─────────────────┐
                    │     PROTO       │
                    │    (solid)      │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
            pour           wisp         distill
              │              │              ↑
              ▼              ▼              │
      ┌───────────────┐  ┌───────────────┐ │
      │      MOL      │  │     WISP      │ │
      │   (liquid)    │  │    (vapor)    │ │
      └───────┬───────┘  └───────┬───────┘ │
              │                  │         │
           squash             squash       │
              │                  │         │
              ▼                  ▼         │
      ┌───────────────┐  ┌───────────────┐ │
      │    DIGEST     │  │  (evaporates) │ │
      │  (condensed)  │  │    or burn    │ │
      └───────────────┘  └───────────────┘ │
              │                            │
              └────────────────────────────┘
                       (experience crystallizes)

Pour: Solid → Liquid

Pour instantiates a proto into a persistent mol - like pouring molten metal into a mold to create a solid casting that will flow through the workflow.

bd pour mol-feature                    # Create mol from proto
bd pour mol-feature --var version=1.0  # With variable substitution

Use cases:

• Feature work that spans sessions
• Important work needing audit trail
• Anything you might need to reference later

Wisp: Solid → Vapor (Sublimation)

Wisp instantiates a proto directly into vapor - sublimation that skips the liquid phase for ephemeral, operational work.

bd wisp mol-patrol                     # Create wisp from proto
bd wisp mol-health-check               # Ephemeral operational task

Use cases:

• Patrol cycles (deacon, witness)
• Health checks and monitoring
• One-shot orchestration runs
• Routine operations with no audit value

Squash: Liquid/Vapor → Condensed

Squash condenses work into a permanent digest - the outcome crystallizes while the execution trace compresses or evaporates.

bd mol squash bd-abc123                              # Squash mol to digest
bd mol squash bd-abc123 --summary="Completed auth"   # With summary

For mols: Creates digest in permanent beads, preserves full outcome For wisps: Creates digest, deletes wisp (vapor condenses to residue)

Burn: Vapor → Nothing

Burn discards a wisp without creating a digest - the steam simply evaporates with no residue.

bd mol burn wisp-123                   # Discard without digest

Use cases:

• Routine patrol cycles with nothing notable
• Failed attempts that don't need recording
• Test runs

Distill: Liquid → Solid (Crystallization)

Distill extracts a reusable proto from an existing mol or epic - the reverse of pour. Experience crystallizes into a template.

bd mol distill bd-abc123 --as "Release Workflow"
bd mol distill bd-abc123 --var feature=auth --var version=1.0

Process:

1. Analyze the existing work structure
2. Extract the pattern (steps, dependencies)
3. Replace concrete values with {{variable}} placeholders
4. Crystallize as a new proto

Use cases:

• Team develops a good workflow organically, wants to reuse it
• Capture tribal knowledge as executable templates
• Create starting points for similar future work

The Polymorphic Bond Operator

Bond is Gas Town's polymorphic combiner - it handles different operand types with different phase behaviors:

Bond: Proto + Proto → Compound Proto

Two solid templates fuse into a larger solid template.

bd mol bond mol-review mol-deploy --as "Review and Deploy"

Creates a compound proto that includes both workflows. The result is a reusable template (solid phase).

Bond: Proto + Mol → Spawn + Attach

A solid template melts into an existing liquid workflow.

bd mol bond mol-hotfix bd-feature-123

The proto is instantiated (as liquid by default) and attached to the existing mol. The new issues become part of the flowing work.

Bond: Proto + Wisp → Spawn + Attach (Vapor)

A solid template sublimates into an existing vapor workflow.

bd mol bond mol-extra-check wisp-patrol-456

The proto spawns as vapor (following the wisp's phase) and attaches.

Bond: Mol + Mol → Compound Mol

Two liquid workflows merge into a larger flowing structure.

bd mol bond bd-feature-123 bd-related-456

Links them via dependency edges. Both continue flowing.

Bond: Wisp + Wisp → Compound Wisp

Two vapor traces merge into a larger ephemeral cloud.

bd mol bond wisp-123 wisp-456

Phase Override Flags

Bond's spawning behavior can be overridden:

# Force liquid when attaching to wisp (found something important!)
bd mol bond mol-critical-bug wisp-patrol --pour

# Force vapor when attaching to mol (ephemeral diagnostic)
bd mol bond mol-temp-check bd-feature --wisp

Flag	Effect	Use Case
--pour	Force spawn as liquid	"This matters, persist it"
--wisp	Force spawn as vapor	"This is ephemeral, let it evaporate"

Cross-Phase Bonding

What happens when you bond liquid and vapor directly?

bd mol bond bd-feature-123 wisp-456    # Mol + Wisp

Answer: Reference-only linking. They connect via dependency edges but stay in their respective stores. No phase change occurs - you're linking across the phase boundary without forcing conversion.

This enables patterns like:

• Patrol wisp discovers issue → creates liquid mol for the fix
• Feature mol needs diagnostic → spawns vapor wisp for the check
• The reference survives even when the wisp evaporates (ID stable)

Agent Attachment: Hooks and Pins

Agents need work attached to them. In Gas Town, this uses hooks and pins.

The Hook

Each agent has a hook - an anchor point where work hangs. It's the agent's "pinned bead" - the top of their inbox, the work they're focused on.

bd hook                                # Show what's on my hook
bd hook --agent deacon                 # Show deacon's hook

Hook states:

• Empty (naked): Agent awaiting work assignment
• Occupied: Agent has work to execute
• Multiple: Agent managing several concurrent mols (rare)

Pin: Attaching Work to Agents

Pin attaches a mol to an agent's hook - the action of assigning work.

bd pin bd-feature-123                  # Pin to my hook
bd pin bd-feature-123 --for witness    # Pin to specific agent's hook
bd unpin                               # Detach current work

The Witness → Polecat flow:

# Witness assigns work to polecat
bd pour mol-feature                    # Create liquid mol
bd pin bd-abc123 --for polecat-ace     # Hang on polecat's hook
gt nudge polecat-ace                   # Wake the polecat

Wisps Don't Need Pinning

Wisps are single-cycle and don't survive session boundaries in the traditional sense. Agents hold them in working memory for one cycle:

# Deacon self-spawns patrol (no pin needed)
bd wisp mol-deacon-patrol              # Create vapor
# ... execute steps ...
bd mol squash <id> --summary="..."     # Condense and dissipate
# Loop

The Epic-Mol Relationship

Epics and mols are isomorphic but represent different mental models.

Epic: The Business View

An epic is a simple mol shape - essentially a TODO list:

epic-root
├── child.1
├── child.2
├── child.3
└── child.4
(flat list, no sibling dependencies, execution order implicit)

Properties:

• One level of children via .N numbering
• No explicit serial/parallel encoding
• Human-readable, business-oriented
• The natural shape most humans create

Mol: The Chemistry View

A mol is the general case - arbitrary graphs with explicit workflow semantics:

mol-root
├── phase-A (epic)
│   ├── task.1 ───blocks──→ task.2 (serial)
│   └── task.3 (parallel with task.1)
├── phase-B (epic) ←───blocked-by─── phase-A
│   └── ...
└── standalone (fanout)
(arbitrary DAG, explicit dependencies encode serial/parallel)

Properties:

• Can contain multiple epics as subgraphs
• Dependency edges encode execution order
• blocks = serial (bottleneck)
• No dep = parallel (fanout)
• conditional = if-fail path

The Relationship

All epics are mols. Not all mols are epics.

Aspect	Epic	Mol
Shape	Flat (root + children)	Arbitrary DAG
Dependencies	Implicit in ordering	Explicit edges
Parallelism	Assumed parallel	Encoded in structure
Mental model	TODO list	Workflow graph
Common use	Simple feature work	Complex orchestration

When you distill an epic, you get a simple proto. When you distill a complex mol, you get a complex proto (preserving structure).

Thermodynamic Properties

Gas Town's chemistry has thermodynamic properties - work is energy flowing through the system.

Work as Energy

Proto (potential energy) → Pour/Wisp → Mol/Wisp (kinetic energy) → Squash → Digest (stored work)

• Protos store potential energy - the capability to do work
• Mols/Wisps are kinetic - work actively flowing
• Digests are stored energy - crystallized outcomes

The Audit Trail as Entropy

Every execution increases entropy - creating more history, more records, more state. Gas Town manages this through:

• Wisps: High entropy, but evaporates (entropy contained)
• Squash: Compresses entropy into minimal digest
• Distill: Reduces entropy by extracting reusable pattern

The CV Chain

Every agent has a chain of work - their CV:

Agent CV = ∑(digests) = crystallized capability proof

Work completed → digest created → agent's chain grows → capability demonstrated.

This is the foundation for capability-based work matching: your work history IS your resume. The ledger speaks.

The Complete Lifecycle

Feature Work (Liquid Path)

# 1. Create work from template
bd pour mol-feature --var name=auth

# 2. Pin to agent
bd pin bd-abc123 --for polecat-ace

# 3. Agent executes steps
bd update bd-abc123.design --status=in_progress
# ... cognition ...
bd close bd-abc123.design
bd update bd-abc123.implement --status=in_progress
# ... and so on

# 4. Squash when complete
bd mol squash bd-abc123 --summary="Implemented auth feature"

# 5. Digest remains in permanent ledger

Patrol Work (Vapor Path)

# 1. Self-spawn wisp (no pin needed)
bd wisp mol-deacon-patrol

# 2. Execute cycle steps
bd close <step-1>
bd close <step-2>
# ...

# 3. Generate summary and squash
bd mol squash <wisp-id> --summary="Patrol complete, no issues"

# 4. Loop
bd wisp mol-deacon-patrol
# ...

Template Creation (Distillation)

# 1. Complete some work organically
# ... team develops release workflow over several iterations ...

# 2. Distill the pattern
bd mol distill bd-release-v3 --as "Release Workflow"

# 3. Result: new proto available
bd pour mol-release-workflow --var version=2.0

Polymers: Large-Scale Composition

Protos can compose into arbitrarily large polymers - chains of molecules that encode complex multi-phase work.

# Create polymer from multiple protos
bd mol bond mol-design mol-implement --as "Design and Implement"
bd mol bond mol-design-implement mol-test --as "Full Dev Cycle"
bd mol bond mol-full-dev mol-deploy --as "End to End"

Polymer properties:

• Preserve phase relationships from constituent protos
• Can encode hours, days, or weeks of work
• Enable "weekend warrior" autonomous operation
• Beads tracks progress; agents execute; humans sleep

The Cognition Sausage Machine

A large polymer is a cognition sausage machine:

Proto Polymer (input)
     │
     ▼
┌─────────────────────────────────────────┐
│           GAS TOWN ENGINE               │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐    │
│  │Pole │  │Pole │  │Pole │  │Pole │    │
│  │cat  │  │cat  │  │cat  │  │cat  │    │
│  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘    │
│     │        │        │        │        │
│     └────────┴────────┴────────┘        │
│              ↓                          │
│         Merge Queue                     │
│              ↓                          │
│          Refinery                       │
└─────────────────────────────────────────┘
     │
     ▼
Completed Work + Digests (output)

Feed in a polymer. Get back completed features, merged PRs, and audit trail.

The Proto Library

Gas Town maintains a library of curated protos - the fuel stockpile:

~/gt/molecules/
├── mol-engineer-in-box/       # Full quality workflow
├── mol-quick-fix/             # Fast path for small changes
├── mol-code-review/           # Pluggable review dimensions
├── mol-release/               # Release workflow
├── mol-deacon-patrol/         # Deacon monitoring cycle
├── mol-witness-patrol/        # Witness worker monitoring
└── mol-polecat-work/          # Standard polecat lifecycle

Library operations:

bd mol list                    # List available protos
bd mol show mol-code-review    # Show proto details
bd pour mol-code-review        # Instantiate for use

Curated vs Organic

• Curated protos: Refined templates in the library, battle-tested
• Organic protos: Distilled from real work, may need refinement
• Path: Organic → refine → curate → library

Digest ID Stability

When a wisp is created, its head bead ID is reserved in permanent storage. This ensures cross-phase references remain valid:

1. bd wisp mol-patrol          → Creates wisp-123 (ID reserved)
2. bd mol bond ... wisp-123    → Reference created
3. bd mol squash wisp-123      → Digest takes same ID
4. Reference still valid       → Points to digest now

Implementation:

• On wisp creation: Write placeholder/tombstone to permanent beads
• On squash: Replace placeholder with actual digest
• Cross-phase references never break

Summary of Operators

Operator	From	To	Effect
pour	Proto	Mol	Instantiate as persistent liquid
wisp	Proto	Wisp	Instantiate as ephemeral vapor
bond	Any + Any	Compound	Combine (polymorphic)
squash	Mol/Wisp	Digest	Condense to permanent record
burn	Wisp	Nothing	Discard without record
distill	Mol/Epic	Proto	Extract reusable template
pin	Mol	Agent	Attach work to agent's hook

Design Implications

For Beads

1. New commands: bd pour, bd wisp, bd pin
2. Flag changes: --persistent → --pour (or phase follows operand)
3. Wisp storage: .beads-wisp/ directory, gitignored
4. Digest ID reservation: Placeholder in permanent store on wisp creation

For Gas Town

1. Daemon: Don't attach permanent molecules for patrol roles
2. Deacon template: Use bd wisp mol-deacon-patrol pattern
3. Polecat lifecycle: Consider wisp-based with digest on completion
4. Hook inspection: bd hook command for debugging

For Agents

1. Polecats: Receive pinned mols, execute, squash, request shutdown
2. Patrol roles: Self-spawn wisps, execute cycle, squash, loop
3. Recovery: Re-read beads state, continue from last completed step

---

Appendix: The Vocabulary

Term	Meaning
Proto	Frozen template molecule (solid phase)
Mol	Flowing work instance (liquid phase)
Wisp	Ephemeral execution trace (vapor phase)
Digest	Condensed permanent record
Pour	Instantiate proto as mol (solid → liquid)
Wisp (verb)	Instantiate proto as wisp (solid → vapor)
Bond	Combine molecules (polymorphic)
Squash	Condense to digest
Burn	Discard wisp without digest
Distill	Extract proto from experience
Hook	Agent's attachment point for work
Pin	Attach mol to agent's hook
Polymer	Large composed proto chain
Epic	Simple mol shape (flat TODO list)

---

The chemistry is the interface. The ledger is the truth. The work gets done.