​

Exec Beads Provider — Architecture & Protocol

​

Motivation

• beads_rust (br) — SQLite + JSONL hybrid with different performance characteristics and no JVM/Dolt dependency
• Custom backup semantics — bead operations that trigger S3 snapshots, git commits, or other persistence strategies
• Alternative databases — PostgreSQL, SQLite, flat files, or any storage backend accessible via CLI

​

Current Architecture

​

Store Interface (9 methods)

type Store interface {
    Create(b Bead) (Bead, error)       // persist new bead → fills ID, Status, CreatedAt
    Get(id string) (Bead, error)       // retrieve by ID
    Update(id string, opts UpdateOpts) error  // modify fields (Description, ParentID, Labels)
    Close(id string) error             // set status to "closed"
    List() ([]Bead, error)             // all beads
    Ready() ([]Bead, error)            // all open beads
    Children(parentID string) ([]Bead, error)  // beads with matching ParentID
    SetMetadata(id, key, value string) error   // key-value metadata on a bead
    MolCook(formula, title string, vars []string) (string, error)  // instantiate molecule
}

​

Three Implementations

​

BdStore-Only Methods (Not in Store Interface)

​

Provider Selection

func beadsProvider(cityPath string) string {
    if v := os.Getenv("GC_BEADS"); v != "" {
        return v
    }
    cfg, err := config.Load(fsys.OSFS{}, filepath.Join(cityPath, "city.toml"))
    if err == nil && cfg.Beads.Provider != "" {
        return cfg.Beads.Provider
    }
    return "bd"
}

[beads]
provider = "bd"    # or "file", or "exec:/path/to/script"

​

What Must Change

​

1. Promote ListByLabel to the Store Interface

• Order history — list all wisps for a order
• Last run time — find most recent wisp for a order
• Event cursor — find max seq: label across order wisps

type Store interface {
    // ... existing 9 methods ...

    // ListByLabel returns beads matching an exact label string.
    // Limit controls max results (0 = unlimited). Results ordered
    // newest first.
    ListByLabel(label string, limit int) ([]Bead, error)
}

​

2. Keep Admin Operations Outside the Store Interface

​

3. Add Exec Beads Provider

​

Exec Beads Protocol

​

Calling Convention

<script> <operation> [args...]

​

Exit Codes

​

Operations

​

Core Store Operations (10 methods)

​

Admin Operations (Optional)

​

Lifecycle Operations (Optional)

​

Wire Format

​

Bead JSON

{
  "id": "WP-42",
  "title": "digest wisp",
  "status": "open",
  "type": "task",
  "created_at": "2026-02-27T10:00:00Z",
  "assignee": "",
  "parent_id": "",
  "ref": "",
  "needs": [],
  "description": "",
  "labels": ["order-run:digest", "pool:dog"]
}

​

Create Request

{
  "title": "my task",
  "type": "task",
  "labels": ["pool:dog"],
  "parent_id": "WP-1"
}

​

UpdateOpts JSON

{
  "description": "updated description",
  "parent_id": "WP-1",
  "labels": ["new-label"]
}

​

MolCookRequest JSON

{
  "formula": "mol-digest",
  "title": "digest run",
  "vars": ["key=value"]
}

​

PurgeOpts JSON

{
  "dry_run": true
}

​

PurgeResult JSON

{
  "purged_count": 5
}

​

Conventions

• JSON on stdin for mutations — avoids shell quoting issues with descriptions, titles, and label values
• JSON on stdout for reads — consistent with bd’s --json output
• Plain text for simple results — mol-cook returns just the ID
• Empty array for no results — list, ready, children, list-by-label return [], never null
• Idempotent close — closing an already-closed bead returns exit 0
• ErrNotFound → exit 1 — get, update, close, set-metadata with unknown ID print error to stderr and exit 1

​

Status Mapping

​

Implementation Plan

​

Package Structure

internal/beads/exec/
├── exec.go          # ExecStore implementing Store interface
├── exec_test.go     # unit tests with fake script
└── json.go          # wire format types (like session/exec/json.go)

​

ExecStore

// ExecStore implements beads.Store by delegating each operation to a
// user-supplied script via fork/exec.
type ExecStore struct {
    script  string
    timeout time.Duration
}

func NewExecStore(script string) *ExecStore {
    return &ExecStore{script: script, timeout: 30 * time.Second}
}

func (s *ExecStore) run(stdinData []byte, args ...string) (string, error) {
    ctx, cancel := context.WithTimeout(context.Background(), s.timeout)
    defer cancel()
    cmd := exec.CommandContext(ctx, s.script, args...)
    cmd.WaitDelay = 2 * time.Second
    // ... same exit code 2 handling as session exec ...
}

​

Provider Selection Update

func newBeadStore(cityPath, cmdName string, stderr io.Writer) (beads.Store, int) {
    provider := beadsProvider(cityPath)
    if strings.HasPrefix(provider, "exec:") {
        script := strings.TrimPrefix(provider, "exec:")
        return beadsexec.NewExecStore(script), 0
    }
    switch provider {
    case "file":
        // ... existing ...
    default:
        // ... existing bd ...
    }
}

​

Config Update

[beads]
provider = "exec:/path/to/gc-beads-br"

export GC_BEADS=exec:gc-beads-br

​

Dependency Map: SDK Primitives vs. Provider Operations

​

beads_rust (br) Gap Analysis

​

Supported (Direct Mapping)

​

Gaps (Script Must Bridge)

​

Not Needed by Store Interface

​

Feasibility Assessment

• Children: Use br list --label=parent:<id> (script adds parent label on create)
• SetMetadata: Use br update --label=meta:key=value (script convention)
• MolCook: Parse formula TOML, create root + step beads, wire parent links. This is the hardest gap — it requires the script to understand Gas City’s formula format.

​

Design Decision: MolCook as Composed vs. Primitive

type Store interface {
    Create(b Bead) (Bead, error)
    Get(id string) (Bead, error)
    Update(id string, opts UpdateOpts) error
    Close(id string) error
    List() ([]Bead, error)
    Ready() ([]Bead, error)
    Children(parentID string) ([]Bead, error)
    SetMetadata(id, key, value string) error
    ListByLabel(label string, limit int) ([]Bead, error)
    MolCook(formula, title string, vars []string) (string, error)  // composed internally for exec
}

​

Migration Path

​

Phase 1: Interface Promotion (This PR)

1. Add ListByLabel(label string, limit int) ([]Bead, error) to Store
2. Implement on MemStore and FileStore (filter existing data)
3. Change cmd/gc/cmd_order.go functions from *BdStore to Store

​

Phase 2: Exec Provider

1. Create internal/beads/exec/ package
2. Implement ExecStore with all Store interface methods
3. Add exec: prefix handling in beadsProvider()
4. Write protocol documentation

​

Phase 3: MolCook Decomposition

1. Extract formula→bead-tree logic from bd mol cook into Go
2. Implement composed MolCook on ExecStore using Create + Update
3. Optionally add composed MolCook to FileStore/MemStore

​

Phase 4: Reference Script

1. Write gc-beads-br script wrapping beads_rust
2. Verify all Gas City operations work end-to-end
3. Document gaps and workarounds

​

Comparison: Session vs. Beads Exec Pattern

​

Open Questions

1. Should Children use a label convention or a first-class parent field? If we use labels (parent:<id>), the script doesn’t need native parent support. But bd has native parent support. Decision: keep ParentID as a first-class field in the wire format; scripts that don’t support it natively use labels internally.
2. Should ListByLabel support multiple labels (AND)? Current BdStore only supports a single label. Keep it simple for now — single label. Multiple-label queries can be composed from single-label results.
3. Purge semantics for exec provider. Purge is dolt-specific (removes closed ephemeral beads from the Dolt database). For exec providers, should this be delegated or composed? Recommendation: delegate as optional (exit 2 = no-op). The script can implement its own cleanup strategy.

​

Shipped Scripts

• gc-beads-br — beads_rust (br) backend. Wraps the br CLI with SQLite + JSONL backing. Dependencies: br, jq, bash.
• gc-beads-k8s — Kubernetes backend. Runs bd inside a lightweight “beads runner” pod via kubectl exec. The pod connects to Dolt running as a StatefulSet inside the cluster. Dependencies: kubectl, jq, bash.